spade 0.0.1

data/sproutcore/frameworks/experimental/README.md

@@ -0,0 +1,23 @@
+SproutCore Experimental Framework
+=================================
+ 
+The SproutCore Experimental framework contains code that is
+not ready to be included in the core framework and is **actively** being
+worked on. This code is being improved with the expectation that
+eventually the code that lives in this parent framework will become
+a part of the core framework. If you are interested in using a framework
+that is experimental, can you do the following in your Buildfile:
+
+    config :your_app, :required => [:sproutcore, :'sproutcore/experimental/example']
+
+which will include the experimental framework and whatever modifications
+it makes to the core framework in your project.
+
+
+### Note
+
+Experimental frameworks may not be kept up to date with the master core
+code, and by nature will be unstable and less tested than the core code.
+We will try our best to maintain experimental code and ensure
+that code that will not make it into the core framework is pruned, but
+there are no guarantees.

data/sproutcore/frameworks/experimental/frameworks/device_motion/README.md

@@ -0,0 +1,11 @@
+Device Motion Framework
+=======================
+ 
+This framework adds accelerometer and gyroscope support to SC.device in
+browsers that support the window.ondeviceorientation and
+window.ondevicemotion events.
+
+
+## Contributors
+
+- Colin Campbell (<colin@sproutcore.com>)

data/sproutcore/frameworks/experimental/frameworks/device_motion/device.js

@@ -0,0 +1,215 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2011 Strobe Inc. and contributors.
+//            Portions ©2008-2010 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+sc_require('platform');
+
+/**
+  h1. Device Motion
+  
+  When a device is moved, some platforms will inform us of its movement
+  (accelerometer) and angle (gyroscope). 
+  
+*/
+SC.mixin(SC.device,
+/** @scope SC.device */ {
+  
+  // ..........................................................
+  // PROPERTIES
+  // 
+  
+  /*
+    TODO [CC] There shouldn't be a need for this property, we should overload
+              the addObserver/removeObserver functions and check for the
+              rotationX/Y/Z keys.
+  */
+  /**
+    Because the device motion events fire every 50ms, for performance reasons
+    you must opt into listening for those events.
+    
+    @property {Boolean}
+    @default NO
+  */
+  listenForDeviceMotion: NO,
+
+  /**
+    Amount, in degrees, that the device is rotated around its x axis. x axis is
+    the plane of the screen and is positive towards the right hand side of
+    the screen, regardless of orientation.
+    
+    SC.device#listenForDeviceMotion must be true for this property to update.
+    
+    @property {Number}
+    @default 0
+  */
+  rotationX: 0,
+  
+  /**
+    Amount, in degrees, that the device is rotated around its y axis (axis runs
+    from the top to the bottom of the device). y axis is the plane of the
+    screen and is positive towards the top of the screen, regardless of
+    orientation.
+    
+    SC.device#listenForDeviceMotion must be true for this property to update.
+    
+    @property {Number}
+    @default 0
+  */
+  rotationY: 0,
+  
+  /**
+    Amount, in degrees, that the device is rotated around its z axis (normal
+    coming "out" of the screen). z axis is perpendicular to the screen and is
+    positive "out" of (or normal to) the screen. This property is only useful
+    if the device has a gyroscope; for devices which lack a gyroscope (use
+    an accelerometer or nothing), this property remains 0.
+    
+    SC.device#listenForDeviceMotion must be true for this property to update.
+    
+    @property {Number}
+    @default 0
+  */
+  rotationZ: 0,
+
+
+  // ..........................................................
+  // SETUP
+  // 
+  
+  setupMotion: function() {
+    SC.RootResponder.responder.listenFor('devicemotion deviceorientation'.w(), window, this);
+  },
+  
+  
+  // ..........................................................
+  // DEVICE MOTION HANDLING
+  // 
+  
+  _scd_listenForDeviceMotionDidChange: function() {
+    if (!SC.RootResponder.responder) return;
+    
+    // we only care about the gyro now, we don't need acceleration
+    if (this.get('listenForDeviceMotion')) {
+      if (SC.platform.hasGyroscope) {
+        SC.Event.add(window, 'deviceorientation', this, this._scd_deviceorientationPoll);
+      } else if (SC.platform.hasAccelerometer) {
+        SC.Event.add(window, 'devicemotion', this, this._scd_devicemotionPoll);
+      } else {
+        SC.Logger.warn("Can't listen for device motion events on a platform that does not support them");
+      }
+    } else {
+      SC.Event.remove(window, 'deviceorientation', this, this._scd_deviceorientationPoll);
+      SC.Event.remove(window, 'devicemotion', this, this._scd_devicemotionPoll);
+    }
+  },
+  
+  /**
+    Fired once every 50ms, informing us of the gyroscope measurements
+  */
+  deviceorientation: function(evt) {
+    evt = evt.originalEvent;
+    
+    if (!SC.platform.hasGyroscope) SC.platform.hasGyroscope = YES;
+    
+    SC.Event.remove(window, 'deviceorientation', this, this.deviceorientation);
+    SC.Event.remove(window, 'devicemotion', this, this.devicemotion);
+    
+    this.addObserver('listenForDeviceMotion', this, this._scd_listenForDeviceMotionDidChange);
+    this.notifyPropertyChange('listenForDeviceMotion');
+  },
+  
+  /** @private
+    Gets called after the first deviceorientation event, used to actually set
+    the rotation values
+  */
+  _scd_deviceorientationPoll: function(evt) {
+    var orientation = this.get('orientation');
+    
+    evt = evt.originalEvent;
+    
+    SC.run(function() {
+      this.beginPropertyChanges();
+      this.set('rotationX', orientation !== 'landscape' ? evt.beta : evt.gamma);
+      this.set('rotationY', orientation !== 'landscape' ? evt.gamma : -evt.beta);
+      this.set('rotationZ', evt.alpha);
+      this.endPropertyChanges();
+    }, this);
+  },
+  
+  /** @private
+    Because we only want to deal with only the gyroscope, if it is firing its event,
+    we wait until two devicemotion events have been fired to decide to use the
+    accelerometer instead.
+  */
+  _devicemotionCalled: NO,
+  
+  /**
+    Fired every 50ms, informing us of the accelerometer measurements
+  */
+  devicemotion: function(evt) {
+    if (!SC.platform.hasAccelerometer) SC.platform.hasAccelerometer = YES;
+    
+    if (this._devicemotionCalled) {
+      // if this happens, and this event fires (ie. the deviceorientation event hasn't)
+      // then we assume the device does not have a gyroscope
+      SC.Event.remove(window, 'deviceorientation', this, this.deviceorientation);
+      SC.Event.remove(window, 'devicemotion', this, this.devicemotion);
+      
+      this.set('rotationZ', 0); // ensure rotationZ does not get any other value
+      this.addObserver('listenForDeviceMotion', this, this._scd_listenForDeviceMotionDidChange);
+      this.notifyPropertyChange('listenForDeviceMotion');
+    } else {
+      this._devicemotionCalled = YES;
+    }
+  },
+  
+  /*
+    TODO [CC] This needs to be expanded on a bit. If you hold the device in weird
+              positions, the rotation values from the accelerometer no longer match those
+              from the gyroscope. What about people who use their iPad in bed?!
+  */
+  /** @private
+    Gets called after the first devicemotion event, if the device has no gyropscope.
+  */
+  _scd_devicemotionPoll: function(evt) {
+    var min = SC.platform.accelerationMinimum,
+        max = SC.platform.accelerationMaximum,
+        spread = max - min,
+        orientation = this.get('orientation'),
+        aX, aY, rX, rY, swap;
+    
+    evt = evt.originalEvent;
+    
+    aX = evt.accelerationIncludingGravity.x;
+    aY = evt.accelerationIncludingGravity.y;
+    
+    if (aX < min) aX = min;
+    else if (aX > max) aX = max;
+    if (aY < min) aY = min;
+    else if (aY > max) aY = max;
+    
+    if (orientation === 'landscape') {
+      swap = aX;
+      aX = aY;
+      aY = swap;
+    }
+    
+    rX = 90 - ((aY-min)/spread) * 180;
+    rY = -90 + ((aX-min)/spread) * 180;
+    
+    SC.run(function() {
+      this.beginPropertyChanges();
+      this.set('rotationX', rX);
+      this.set('rotationY', rY);
+      this.endPropertyChanges();
+    }, this);
+  }
+
+});
+
+SC.ready(function() {
+  SC.device.setupMotion();
+});

data/sproutcore/frameworks/experimental/frameworks/device_motion/platform.js

@@ -0,0 +1,67 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2011 Strobe Inc. and contributors.
+//            Portions ©2008-2010 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+SC.mixin(SC.platform,
+/** @scope SC.platform */ {
+
+  /**
+    YES if the ondeviceorientation event on window is supported.
+    
+    @property {Boolean}
+    @default NO
+  */
+  supportsGyroscope: ('ondeviceorientation' in window),
+  
+  /**
+    YES if the ondeviceorientation event on window has actually been
+    fired. Some platforms have the event but will never fire it.
+    
+    @property {Boolean}
+    @default NO
+  */
+  hasGyroscope: NO,
+  
+  /**
+    YES if the ondevicemotion event on window is supported.
+    
+    @property {Boolean}
+    @default NO
+  */
+  supportsAccelerometer: ('ondevicemotion' in window),
+  
+  /**
+    YES if the ondevicemotion event on window has actually been
+    fired. Some platforms have the event but will never fire it.
+    
+    @property {Boolean}
+    @default NO
+  */
+  hasAccelerometer: NO,
+  
+  /*
+    TODO [CC] Find out the actual values on a multitude of devices.
+              We would want this to be a 'normal' use value...
+  */
+  /**
+    @property {Number}
+    @default -10
+  */
+  accelerationMinimum: function() {
+    // we may want finer grained control of this by platform later
+    return -10;
+  }(),
+  
+  /**
+    @property {Number}
+    @default 10
+  */
+  accelerationMaximum: function() {
+    // we may want finer grained control of this by platform later
+    return 10;
+  }()
+
+});

data/sproutcore/frameworks/experimental/frameworks/polymorphism/README.md

@@ -0,0 +1,34 @@
+Polymorphism Framework
+======================
+ 
+This framework adds polymorphism support to SC.Record relationships.
+Right now, only one-to-one polymorphism is supported, but to-many
+support is planned.
+
+
+## Using the Framework
+
+In order to use the polymorphic to-one relationship, include this
+framework in your Buildfile. Inside your Records, you can define
+a relationship like this:
+
+    MyApp.Child = SC.Record.extend({
+	    parent: SC.Record.toOneOf(['MyApp.Male', 'MyApp.Female'], {typeKey: 'parentType'}),
+	    parentType: SC.Record.attr(String)
+	});
+
+You need to pass in a hash like the following when creating the record:
+
+    {parent: 1, parentType: 'MyApp.Male'}
+
+
+For other, more flexible, ways of using this polymorphic support,
+see the unit tests or source code.
+
+<!--
+	TODO Write more examples
+-->
+
+## Contributors
+
+- Colin Campbell (<colin@sproutcore.com>)

data/sproutcore/frameworks/experimental/frameworks/polymorphism/models/polymorphic_single_attribute.js

@@ -0,0 +1,183 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+/** @class
+  
+  PolymorphicSingleAttribute is a subclass of SingleAttribute and handles polymorphic
+  to-one relationships.
+  
+  @extends SC.SingleAttribute
+  @author Colin Campbell
+  @since SproutCore 1.0
+*/
+SC.PolymorphicSingleAttribute = SC.SingleAttribute.extend(
+/** @scope SC.PolymorphicSingleAttribute.prototype */ {
+
+  /**
+    Contains information on how to transform from and from the passed attribute values.
+    This property is required so the attribute knows which type to use for the relationship.
+    If it is not included, it will default to the first provided type.
+    
+    @property {String}
+    @default null
+  */
+  typeKey: null,
+  
+  /**
+    Provides the ability to map the type names provided by the attribute value into
+    something usable for record relationships. For example, you may need to store
+    record names on the server but only with the class name, not the fully qualified
+    path name (ie. 'Record' vs. 'MyApp.Record'). If the passed records are:
+    
+      ['MyApp.Foo', 'MyApp.Bar']
+    
+    then your typeMap may be
+    
+      ['Foo', 'Bar']
+    
+    'Foo' and 'Bar' are what gets saved to the datahash when writing to the server,
+    and the types are used for the relationship within the application.
+    
+    @property {Array of Strings}
+    @default null
+  */
+  typeMap: null,
+  
+  /**
+    Returns the type, resolved to a class.  If the type property is a regular
+    class, returns the type unchanged.  Otherwise attempts to lookup the 
+    type as a property path.
+    
+    @property {Object}
+  */
+  typeClass: function() {
+    var ret = this.get('type'),
+        l, i, type;
+    if (SC.isArray(ret)) {
+      l = ret.get('length');
+      for (i=0; i<length; i++) {
+        type = ret.objectAt(i);
+        if (SC.typeOf(type) === SC.T_STRING) ret.replace(i, 1, SC.objectForPropertyPath(type));
+      }
+    } else {
+      SC.Logger.warn("%@ is a polymorphic relationship without an array of types".fmt(this));
+      if (SC.typeOf(ret) === SC.T_STRING) ret = SC.objectForPropertyPath(ret);
+    }
+    return ret ;
+  }.property('type').cacheable(),
+
+  /** @private
+    Override the transform function, as we need it to change depending on the record.
+    
+    @param {Class} typeClass The class of the type
+    @param {SC.Record} record The record of this attribute
+  */
+  transform: function(klass) {
+    var transforms = SC.RecordAttribute.transforms,
+        ret ;
+    
+    // walk up class hierarchy looking for a transform handler
+    while(klass && !(ret = transforms[SC.guidFor(klass)])) {
+      // check if super has create property to detect SC.Object's
+      if(klass.superclass.hasOwnProperty('create')) klass = klass.superclass;
+      // otherwise return the function transform handler
+      else klass = SC.T_FUNCTION;
+    }
+    
+    return ret;
+  },
+  
+  /**
+    Converts the passed value into the core attribute value. Uses the polymorphism
+    information provided to determine the correct type.
+    
+    @param {SC.Record} record the record instance
+    @param {String} key the key used to access this attribute on the record
+    @param {Object} value the property value
+    @returns {Object} attribute value
+  */
+  toType: function(record, key, value) {
+    var types = this.get('type'),
+        typeKey = this.get('typeKey'),
+        typeMap = this.get('typeMap'),
+        type, transform, idx;
+    
+    if (typeKey) {
+      type = record.get(typeKey);
+    } else if (SC.isArray(types)) {
+      // default to the first object if no type is provided
+      type = types.get('firstObject');
+    }
+    
+    if (typeMap) {
+      idx = typeMap.indexOf(type);
+      if (idx > -1) {
+        type = types[idx];
+      } else {
+        SC.Logger.warn("Polymorphic map on property %@ for %@ did not exist on %@".fmt(key, type, record.constructor.toString()));
+      }
+    }
+    
+    if (types.indexOf(type) > -1) {
+      if (SC.typeOf(type) === SC.T_STRING) type = SC.objectForPropertyPath(type);
+      transform = this.transform(type);
+      if (transform && transform.to) {
+        value = transform.to(value, this, type, record, key);
+      }
+    } else {
+      SC.Logger.warn("%@ is not a type on %@ of %@".fmt(type.toString(), key, record.constructor.toString()));
+    }
+    
+    return value;
+  },
+  
+  /** 
+    Converts the passed value from the core attribute value. Uses the polymorphism
+    information provided to determine the correct type, and sets the typeKey attribute
+    on the record.
+    
+    @param {SC.Record} record the record instance
+    @param {String} key the key used to access this attribute on the record
+    @param {Object} value the property value
+    @returns {Object} attribute value
+  */
+  fromType: function(record, key, value) {
+    var types = this.get('type'),
+        type = value.constructor,
+        typeString = type.toString(),
+        typeKey = this.get('typeKey'),
+        typeMap = this.get('typeMap'),
+        transform, idx;
+    
+    if (!SC.empty(typeString)) {
+      if (typeMap) {
+        idx = types.indexOf(typeString);
+        if (idx > -1) {
+          typeString = typeMap[idx];
+        } else {
+          SC.Logger.warn("Polymorphic map on property %@ for %@ did not exist on %@".fmt(key, typeString, record.constructor.toString()));
+        }
+      }
+      
+      if (typeKey) {
+        record.set(typeKey, typeString);
+      }
+    } else {
+      SC.Logger.warn("Could not determine type of %@ for polymorphic relation %@ on %@".fmt(value, key, record));
+      type = types.get('firstObject');
+      if (SC.typeOf(type) === SC.T_STRING) type = SC.objectForPropertyPath(type);
+    }
+    
+    transform = this.transform(type);
+    
+    if (transform && transform.from) {
+      value = transform.from(value, this, type, record, key);
+    }
+    return value;
+  }
+
+});