document the transform functions, refactor to allow for api viewing

enyojs · May 21, 2012 · d210641 · d210641
1 parent f9de0b2
commit d210641
Showing 1 changed file with 89 additions and 34 deletions.
diff --git a/source/dom/transform.js b/source/dom/transform.js
@@ -1,55 +1,38 @@
 //* @protected
-enyo.mixin(enyo.dom, {
-	canAccelerate: function() {
-		return this.accelerando !== undefined ? this.accelerando: document.body && (this.accelerando = this.calcCanAccelerate());
-	},
-	calcCanAccelerate: function() {
+(function() {
+	enyo.dom.calcCanAccelerate = function() {
 		/* Android 2 is a liar: it does NOT support 3D transforms, even though Perspective is the best check */
 		if (enyo.platform.android <= 2) {
 			return false;
 		}
-		var p$ = ["perspective", "msPerspective", "MozPerspective", "WebkitPerspective", "OPerspective"];
+		var p$ = ["perspective", "WebkitPerspective", "MozPerspective", "msPerspective", "OPerspective"];
 		for (var i=0, p; p=p$[i]; i++) {
 			if (typeof document.body.style[p] != "undefined") {
 				return true;
 			}
 		}
 		return false;
-	},
-	cssTransformProps: ["-webkit-transform", "-moz-transform", "-ms-transform", "-o-transform", "transform"],
-	styleTransformProps: ["webkitTransform", "MozTransform", "msTransform", "OTransform", "transform"],
-	getCssTransformProp: function() {
+	};
+	var cssTransformProps = ["transform", "-webkit-transform", "-moz-transform", "-ms-transform", "-o-transform"];
+	var styleTransformProps = ["transform", "webkitTransform", "MozTransform", "msTransform", "OTransform"];
+	enyo.dom.getCssTransformProp = function() {
 		if (this._cssTransformProp) {
 			return this._cssTransformProp;
 		}
-		var i = enyo.indexOf(this.getStyleTransformProp(), this.styleTransformProps);
-		return this._cssTransformProp = this.cssTransformProps[i];
-	},
-	getStyleTransformProp: function() {
+		var i = enyo.indexOf(this.getStyleTransformProp(), styleTransformProps);
+		return this._cssTransformProp = cssTransformProps[i];
+	};
+	enyo.dom.getStyleTransformProp = function() {
 		if (this._styleTransformProp || !document.body) {
 			return this._styleTransformProp;
 		}
-		for (var i = 0, p; p = this.styleTransformProps[i]; i++) {
+		for (var i = 0, p; p = styleTransformProps[i]; i++) {
 			if (typeof document.body.style[p] != "undefined") {
 				return this._styleTransformProp = p;
 			}
 		}
-	},
-	transformValue: function(inControl, inTransform, inValue) {
-		var d = inControl.domTransforms = inControl.domTransforms || {};
-		d[inTransform] = inValue;
-		this.transformsToDom(inControl);
-	},
-	accelerate: function(inControl, inValue) {
-		var v = inValue == "auto" ? this.canAccelerate() : inValue;
-		this.transformValue(inControl, "translateZ", v ? 0 : null);
-	},
-	transform: function(inControl, inTransforms) {
-		var d = inControl.domTransforms = inControl.domTransforms || {};
-		enyo.mixin(d, inTransforms);
-		this.transformsToDom(inControl);
-	},
-	domTransformsToCss: function(inTransforms) {
+	};
+	enyo.dom.domTransformsToCss = function(inTransforms) {
 		var n, v, text = '';
 		for (n in inTransforms) {
 			v = inTransforms[n];
@@ -58,8 +41,8 @@ enyo.mixin(enyo.dom, {
 			}
 		}
 		return text;
-	},
-	transformsToDom: function(inControl) {
+	};
+	enyo.dom.transformsToDom = function(inControl) {
 		var t = this.domTransformsToCss(inControl.domTransforms);
 		var st = inControl.hasNode() ? inControl.node.style : null;
 		var ds = inControl.domStyles;
@@ -74,4 +57,76 @@ enyo.mixin(enyo.dom, {
 			}
 		}
 	}
-});
+	//* @public
+	/**
+		Returns true if platform supports CSS3 3D Transforms.
+
+		Typically used like this:
+
+			if (enyo.dom.canAccelerate()) {
+				enyo.dom.transformValue(this.$.slidingThing, "translate3d", x + "," + y + "," + "0")
+			} else {
+				enyo.dom.transformValue(this.$.slidingThing, "translate", x + "," + y);
+			}
+
+	*/
+	enyo.dom.canAccelerate = function() {
+		return this.accelerando !== undefined ? this.accelerando: document.body && (this.accelerando = this.calcCanAccelerate());
+	};
+	/**
+		Applies a series of transforms to _inControl_, using the platform's prefixed transform property.
+
+		**Note:** Transforms are not commutative, so order is important
+
+		Transform values are updated by successive calls:
+
+			enyo.dom.transform(control, {transform: "30px, 40px", scale: 2, rotate: "20deg"});
+			enyo.dom.transform(control, {scale: 3, skewX: "-30deg"});
+
+		is equivalent to:
+
+			enyo.dom.transform(control, {transform: "30px, 40px", scale: 3, rotate: "20deg", skewX: "-30deg"});
+
+		When applying these transforms in webkit browser, this is equivalent to:
+
+			control.applyStyle("-webkit-transform", "translate(30px, 40px) scale(3) rotate(20deg) skewX(-30deg)");
+
+		And in firefox, this is equivalent to:
+
+			control.applyStyle("-moz-transform", "translate(30px, 40px) scale(3) rotate(20deg) skewX(-30deg)");
+
+	*/
+	enyo.dom.transform = function(inControl, inTransforms) {
+		var d = inControl.domTransforms = inControl.domTransforms || {};
+		enyo.mixin(d, inTransforms);
+		this.transformsToDom(inControl);
+	};
+
+	/**
+		Apply a single transform to _inControl_.
+
+		Example:
+
+			tap: function(inSender, inEvent) {
+				var c = inEvent.originator;
+				var r = c.rotation || 0;
+				r = (r + 45) % 360;
+				c.rotation = r;
+				enyo.dom.transformValue(c, "rotate", r);
+			}
+
+		This will rotate the tapped control by 45 degrees clockwise.
+	*/
+	enyo.dom.transformValue = function(inControl, inTransform, inValue) {
+		var d = inControl.domTransforms = inControl.domTransforms || {};
+		d[inTransform] = inValue;
+		this.transformsToDom(inControl);
+	};
+	/**
+		Applies a transform that should trigger GPU compositing for _inControl_
+	*/
+	enyo.dom.accelerate = function(inControl, inValue) {
+		var v = inValue == "auto" ? this.canAccelerate() : inValue;
+		this.transformValue(inControl, "translateZ", v ? 0 : null);
+	};
+})();