DeviceOrientation Events

The Mozilla Dev Derby is a pretty cool thing. Developers from around the world can openly add any demo to the site, and if their demo lines up with the prescribed derby for the month, they are automatically entered to win a prize (t-shirt, cool bag, android device). I decided I would enter again for the January 2012 derby based on Orientation. I made two demos.

catch

The first one called “Catch” which you are attempting to catch a randomly generated ball in the shortest amount of time possible. I have personally found it incredibly addicting to get the perfect game, or at least my best attempt at it and I even wrote the source code. What I learned in developing this app was a couple of things. One, there isn’t a ton of documentation on the web about the DeviceOrientationEvent. Two, its pretty straightforward to detect the orientation and utilize it to move an object. Here is the basic of my app:

 /*orientation stuffs*/
var initOrientation = function() {
    var count = 0, gam = 0, bet = 0;
    if (window.DeviceOrientationEvent) {
        window.addEventListener("deviceorientation", function(e) {
            //gamma = left to right
            //beta = front back
            //alpha = compass dir
            count = count + 1;
            gam += e.gamma;
            bet += e.beta;

            if (count === 0 || count % 10 === 0) {
                orientationYo(gam, bet);
                gam = 0;
                bet = 0;
            }
        }, false);
    }
};

//handle orientation
var orientationYo = function(ltr, ftb) {
    coor.x = coor.x + ltr;
    coor.y = coor.y + ftb;
    if (!gameState.victory && gameState.playing) {
        tgt.move(coor);   
    }
};

so that handles the detection of the orientation event, next I simply added the move call to my target (tgt) which looks like this:

var tgt = {
    isDrawing: false,
    collided: false,
    start: function(coordinates) {
        this.drawIt(coordinates);
        this.isDrawing = true;
    },
    drawIt: function (coordinates) {
        ctx.clearRect(0, 0, canvasWidth, canvasHeight);
        ctx.fillStyle = b2_color;
        ctx.beginPath();
        ctx.arc(coordinates.x, coordinates.y, 25, 0, Math.PI * 2, true);
        ctx.fill();
    },
    move: function(coordinates) {
        if (this.isDrawing) {
          this.checkBounds(coordinates);
          this.drawIt(coordinates);
        }
    },
    finish: function(coordinates) {
        this.isDrawing = false;
        ctx.lineTo(coordinates.x, coordinates.y);
        ctx.stroke();
        ctx.closePath();                
    },
    checkBounds: function(coordinates) {
         if (coordinates.y > bound.y2) {
            coordinates.y = bound.y2;
          } else if (coordinates.y < bound.y1) {
            coordinates.y = bound.y1;
          } else if (coordinates.x > bound.x2) {
            coordinates.x = bound.x2;
          } else if (coordinates.x < bound.x1) {
            coordinates.x = bound.x1;
          }
    }
};

collision detection is handled by my randomly placed bouncing ball, which detects when the target ball moves into its path:

checkObjectCollisions: function() {
    var imgData = ctx.getImageData(this.position.x + this.velocity.x1, this.position.y + this.velocity.x2, r, r),
        pix = imgData.data;
    for (i = 0, n = pix.length; i < n; i += 4) {
        if (pix[i] !== 0) {
            this.collided = true;
            if (Math.abs(this.velocity.x1) > Math.abs(this.velocity.x2)){
                this.velocity.x1 = -this.velocity.x1 * drag;
            } else {
                this.velocity.x2 = -this.velocity.x2 * drag;
            }
            break;
        } else {
            this.collided = false;
        }
    }
}

I am pretty happy with the game, its clean and works nicely. You can check it out here

compass

The other is a simple web compass where I utilize the DeviceOrientationEvent to get the cardinal direction your phone or device is facing. There are two cool (in my opinion) things that happened here. One is that to me it seems the device orientation event as defined states that the DeviceOrientationEvent.alpha ranges from 0 to 360 which to me is a 361 degree circle. The second is that I was able to utilize the offline caching capabilities of the modern web to make the compass available to a device event when not connected to the internet. This is done in minimal lines of code. The HTML and JavaScript are as follows:

<!-- This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this file,
You can obtain one at http://mozilla.org/MPL/2.0/.  -->

<!DOCTYPE html>
<html manifest="compass.appcache">
<head>
<meta charset=utf-8 />
<title>Cardinal Direction Compass</title>
<style>
  .pointer {
    height: 0;
    width: 0;
    border-left: 3em solid transparent;
    border-right: 3em solid transparent;
    border-bottom: 12em solid black;
    margin: -10px 0 0 -40px;
    top: 40%;
    left: 50%;
    position: absolute;
  }
  .n {
    top: 20%;
    left:50%;
    position:absolute;
    font:8em Helvetica;
    margin: 0 0 0 -40px;
  }
  </style>
  <script src="js/jquery.js"></script>
</head>
<body>
  <div class="n">N<br><br><br><br>S</div>
  <div class="pointer"></div>
<script>
        $(document).ready(function() {

          var rotate = function (deg) {  
              $(".n").css({ "-moz-transform": "rotate(0deg)"});
              $(".n").css({ "-moz-transform": "rotate(" + deg + "deg)"});

              $(".n").css({ "-o-transform": "rotate(0deg)"});
              $(".n").css({ "-o-transform": "rotate(" + deg + "deg)"});

              $(".n").css({ "-ms-transform": "rotate(0deg)"});
              $(".n").css({ "-ms-transform": "rotate(" + deg + "deg)"});

              $(".n").css({ "-webkit-transform": "rotate(0deg)"});
              $(".n").css({ "-webkit-transform": "rotate(" + deg + "deg)"});

              $(".n").css({ "transform": "rotate(0deg)"});
              $(".n").css({ "transform": "rotate(" + deg + "deg)"});
          };
          if (window.DeviceOrientationEvent) {
            window.addEventListener("deviceorientation", function (e) {
              rotate(360 - e.alpha);
            }, false);
          }

        });
        </script>
  </body>
</html>

The final point I’d like to make is that due to what I thought was minimal documentation, I participated in a Mozilla Doc Sprint last weekend to update the Documentation surrounding the DeviceOrientationEvent. Doing my part in the web development community was both rewarding and a learning experience. I encourage anyone to try it out as well.

$.widget

I have lately been looking to become more involed with open source projects and for starters I have been looking at jQuery UI and jQuery Mobile. Both are amazing projects and share many of the same characteristics in their code. This is because in both cases, the majority of the functionality is inherited from the jQuery UI widget factory. If I’m going to become involved in this project I should understand how this works, so the following is my breakdown of the code as I understand it.

The widget factory looks like the following:

$.widget = function( name, base, prototype ) {
    var namespace = name.split( "." )[ 0 ],
        fullName;
    name = name.split( "." )[ 1 ];
    fullName = namespace + "-" + name;

    if ( !prototype ) {
        prototype = base;
        base = $.Widget;
    }

    // create selector for plugin
    $.expr[ ":" ][ fullName ] = function( elem ) {
        return !!$.data( elem, name );
    };

    /* OTHER STUFF */
}

I’ll get to the stuff in a second, but lets see what we’ve already learned here. First I see that widget can take up to three arguments (name, base, prototype), and example might be something like

$.widget("cg.awesomewidget, "ui.button", { /*...*/})

here name or “cg.awesomewidget” becomes the namespace and fullname so in my example I have namespaced it to “cg” with a fullname of “cg-awesomewidget”. I also see that we check if prototype is provided, if it is not we assume that we are not inheriting from a named widget, set the base parameter to prototype and set the base to the main $.Widget base object. Okay that sounds more messy than it is. Lets try to rephrase. The base is an optional parameter telling the widget factory we want to inherit from a known widget. In my example above its “ui.button”. If that parameter is not provided it simply pulls from the base $.Widget. So we know that any widget will carry the prototype base of $.Widget for starters. Now, what about this prototype? This is the base object literal that the widget makes its prototype. Sweet right? The next fun fact is that our widget gets its very own shiny new custom selector $(“:cg-awesomewidget”).

Next the object is constructed via the jQuery.extend() method as follows:

$[ namespace ] = $[ namespace ] || {};
// create the constructor using $.extend() so we can carry over any
// static properties stored on the existing constructor (if there is one)
$[ namespace ][ name ] = $.extend( function( options, element ) {
    // allow instantiation without "new" keyword
    if ( !this._createWidget ) {
        return new $[ namespace ][ name ]( options, element );
    }

    // allow instantiation without initializing for simple inheritance
    // must use "new" keyword (the code above always passes args)
    if ( arguments.length ) {
        this._createWidget( options, element );
    }
}, $[ namespace ][ name ], { version: prototype.version } );

here the $[ namespace ][ name ] object is merged together with the prototype.version into the existing constructor as described in the comments. Then the options are passed along to the base. Again this is done via jQuery extend.

var basePrototype = new base();
// we need to make the options hash a property directly on the new instance
// otherwise we'll modify the options hash on the prototype that we're
// inheriting from
basePrototype.options = $.widget.extend( {}, basePrototype.options );

This is followed up with a call to $.each() that checks all the functions of the base and applies those to our new widget.

$.each( prototype, function( prop, value ) {
    if ( $.isFunction( value ) ) {
        prototype[ prop ] = (function() {
            var _super = function() {
                return base.prototype[ prop ].apply( this, arguments );
            };
            var _superApply = function( args ) {
                return base.prototype[ prop ].apply( this, args );
            };
            return function() {
                var __super = this._super,
                    __superApply = this._superApply,
                    returnValue;

                this._super = _super;
                this._superApply = _superApply;

                returnValue = value.apply( this, arguments );

                this._super = __super;
                this._superApply = __superApply;

                return returnValue;
            };
        }());
    }
});

After all of this its time to put it all together. The widget prototype is now set via extend where we extend our basePrototype (widget) merging in the new widget and prototype. The last thing needed is a call to $.widget.bridge() which creates an instance of the object.

$[ namespace ][ name ].prototype = $.widget.extend( basePrototype, {
    namespace: namespace,
    widgetName: name,
    widgetEventPrefix: name,
    widgetBaseClass: fullName
}, prototype );

$.widget.bridge( name, $[ namespace ][ name ] );

That concludes our walkthrough of the jQuery UI widget factory. Fairly amazing when you look at how simple it is to create a widget based on this. A simple example is a look at jquery.ui.tooltip.js