From 24b483db367291b72170f969de78efcb1a9b95bd Mon Sep 17 00:00:00 2001
From: Valerio Virgillito
Date: Thu, 3 May 2012 22:53:07 -0700
Subject: integrating the latest montage version

Signed-off-by: Valerio Virgillito <valerio@motorola.com>
---
 node_modules/montage/ui/button.reel/button.js | 214 ++++++++++++++++++++------
 1 file changed, 164 insertions(+), 50 deletions(-)

(limited to 'node_modules/montage/ui/button.reel/button.js')

diff --git a/node_modules/montage/ui/button.reel/button.js b/node_modules/montage/ui/button.reel/button.js
index 315cf505..eead3124 100644
--- a/node_modules/montage/ui/button.reel/button.js
+++ b/node_modules/montage/ui/button.reel/button.js
@@ -4,46 +4,63 @@
  (c) Copyright 2011 Motorola Mobility, Inc.  All Rights Reserved.
  </copyright> */
  /*global require, exports*/
+
+/**
+    @module "montage/ui/button.reel"
+    @requires montage/core/core
+    @requires montage/ui/component
+    @requires montage/ui/native-control
+    @requires montage/ui/composer/press-composer
+*/
 var Montage = require("montage").Montage,
     Component = require("ui/component").Component,
     NativeControl = require("ui/native-control").NativeControl,
     PressComposer = require("ui/composer/press-composer").PressComposer;
-/**
- * The Button input
- */
-var Button = exports.Button = Montage.create(NativeControl, {
-
-    /**
-    @event
-    @name action
-    @param {Event} event
-
-    Dispatched when the button is activated through a mouse click, finger tap,
-    or when focused and the spacebar is pressed.
-    */
-
-    /**
-    @event
-    @name hold
-    @param {Event} event
-
-    Dispatched when the button is pressed for a period of time, set by
-    {@link holdTimeout}.
-    */
 
 /**
-  Description TODO
-  @private
+    Wraps a native <code>&lt;button></code> or <code>&lt;input[type="button"]></code> HTML element. The element's standard attributes are exposed as bindable properties.
+    @class module:"montage/ui/button.reel".Button
+    @extends module:montage/native-control.NativeControl
+    @example
+<caption>JavaScript example</caption>
+var b1 = Button.create();
+b1.element = document.querySelector("btnElement");
+b1.addEventListener("action", function(event) {
+    console.log("Got event 'action' event");
+});
+    @example
+<caption>Serialized example</caption>
+{
+    "aButton": {
+        "prototype": "montage/ui/button.reel",
+        "properties": {
+            "element": {"#": "btnElement"}
+        },
+        "listeners": [
+            {
+                "type": "action",
+                "listener": {"@": "appListener"}
+            }
+        ]
+    },
+    "listener": {
+        "prototype": "appListener"
+    }
+}
+&lt;button data-montage-id="btnElement"></button>
 */
+var Button = exports.Button = Montage.create(NativeControl, /** @lends module:"montage/ui/button.reel".Button# */ {
+
     _preventFocus: {
         enumerable: false,
         value: false
     },
 
 /**
-        Description TODO
-        @type {Function}
-        @default {Boolean} false
+    Specifies whether the button should receive focus or not.
+    @type {boolean}
+    @default false
+    @event longpress
 */
     preventFocus: {
         get: function () {
@@ -58,6 +75,10 @@ var Button = exports.Button = Montage.create(NativeControl, {
         }
     },
 
+
+/**
+    Enables or disables the Button from user input. When this property is set to <code>false</code>, the "disabled" CSS style is applied to the button's DOM element during the next draw cycle. When set to <code>true</code> the "disabled" CSS class is removed from the element's class list.
+*/
     //TODO we should prefer positive properties like enabled vs disabled, get rid of disabled
     enabled: {
         dependencies: ["disabled"],
@@ -70,7 +91,7 @@ var Button = exports.Button = Montage.create(NativeControl, {
     },
 
     /**
-        The Montage converted used to convert or format values displayed by this Button instance.
+        A Montage converter object used to convert or format the label displayed by the Button instance. When a new value is assigned to <code>label</code>, the converter object's <code>convert()</code> method is invoked, passing it the newly assigned label value.
         @type {Property}
         @default null
     */
@@ -86,15 +107,14 @@ var Button = exports.Button = Montage.create(NativeControl, {
     _labelNode: {value:undefined, enumerable: false},
 
     _label: { value: undefined, enumerable: false },
+
     /**
-        The label for the button.
+        The label for the button. In an &lt;input> element this is taken from the element's <code>value</code> attribute. On any other element (including &lt;button>) this is the first child node which is a text node. If one isn't found then it will be created.
 
-        In an `<input>` element this is the value property. On any other element
-        (including `<button>`) this is the first child node which is a text node.
-        If one isn't found it will be created.
+        If the button has a non-null <code>converter</code> property, the converter object's <code>convert()</code> method is called on the value before being assigned to the button instance.
 
-        @type {Property}
-        @default {String} element value
+        @type {string}
+        @default undefined
     */
     label: {
         get: function() {
@@ -123,14 +143,16 @@ var Button = exports.Button = Montage.create(NativeControl, {
     },
 
     /**
-    How long a press has to last for a hold event to be dispatched
+        The amount of time in milliseconds the user must press and hold the button a <code>hold</code> event is dispatched. The default is 1 second.
+        @type {number}
+        @default 1000
     */
-    holdTimeout: {
+    holdThreshold: {
         get: function() {
-            return this._pressComposer.longPressTimeout;
+            return this._pressComposer.longPressThreshold;
         },
         set: function(value) {
-            this._pressComposer.longPressTimeout = value;
+            this._pressComposer.longPressThreshold = value;
         }
     },
 
@@ -139,20 +161,15 @@ var Button = exports.Button = Montage.create(NativeControl, {
         value: null
     },
 
-    /**
-    True when the button is being interacted with, either through mouse click or
-    touch event.
-    @private
-    */
     _active: {
         enumerable: false,
         value: false
     },
 
     /**
-    Description TODO
-    @type {Function}
-    @default {Boolean} false
+        This property is true when the button is being interacted with, either through mouse click or touch event, otherwise false.
+        @type {boolean}
+        @default false
     */
     active: {
         get: function() {
@@ -164,6 +181,12 @@ var Button = exports.Button = Montage.create(NativeControl, {
         }
     },
 
+    // HTMLInputElement/HTMLButtonElement methods
+
+    blur: { value: function() { this._element.blur(); } },
+    focus: { value: function() { this._element.focus(); } },
+    // click() deliberately omitted (it isn't available on <button> anyways)
+
     didCreate: {
         value: function() {
             this._pressComposer = PressComposer.create();
@@ -202,6 +225,7 @@ var Button = exports.Button = Montage.create(NativeControl, {
 
             if (!this._preventFocus) {
                 this._element.focus();
+
             }
         }
     },
@@ -218,7 +242,6 @@ var Button = exports.Button = Montage.create(NativeControl, {
 
     handleKeyup: {
         value: function(event) {
-            console.log(event.keyCode);
             // action event on spacebar
             if (event.keyCode === 32) {
                 this.active = false;
@@ -241,6 +264,7 @@ var Button = exports.Button = Montage.create(NativeControl, {
 
     /**
     Called when all interaction is over.
+    @private
     */
     handlePressCancel: {
         value: function(event) {
@@ -292,16 +316,21 @@ var Button = exports.Button = Montage.create(NativeControl, {
                 }
             }
 
-            this._element.addEventListener("keyup", this, false);
-
             this.needsDraw = true;
         }
     },
 
+    prepareForDraw: {
+        value: function() {
+            this._element.addEventListener("keyup", this, false);
+        }
+    },
+
 
     /**
     Draws the label to the DOM.
     @function
+    @private
     */
     _drawLabel: {
         enumerable: false,
@@ -330,16 +359,101 @@ var Button = exports.Button = Montage.create(NativeControl, {
     }
 });
 
-Button.addAttributes({
+// TODO: Display events in JSDoc output
+ /**
+ @event
+ @name action
+ @param {Event} event
+
+ Dispatched when the button is activated through a mouse click, finger tap,
+ or when focused and the spacebar is pressed.
+ */
+
+ /**
+ @event
+ @name hold
+ @param {Event} event
+
+ Dispatched when the button is pressed for a period of time, set by
+ {@link holdThreshold}.
+ */
+
+Button.addAttributes( /** @lends module:"montage/ui/button.reel".Button# */{
+
+/**
+    Specifies whether the button should be focused as soon as the page is loaded.
+    @type {boolean}
+    @default false
+*/
     autofocus: {value: false, dataType: 'boolean'},
+
+/**
+    When true, the button is disabled to user input and "disabled" is added to its CSS class list.
+    @type {boolean}
+    @default false
+*/
     disabled: {value: false, dataType: 'boolean'},
+
+/**
+    The value of the id attribute of the form with which to associate the component's element.
+    @type {string}
+    @default null
+*/
     form: null,
+
+/**
+    The URL to which the form data will be sumbitted.
+    @type {string}
+    @default null
+*/
     formaction: null,
+
+/**
+    The content type used to submit the form to the server.
+    @type {string}
+    @default null
+*/
     formenctype: null,
+
+/**
+    The HTTP method used to submit the form.
+    @type {string}
+    @default null
+*/
     formmethod: null,
+
+/**
+    Indicates if the form should be validated upon submission.
+    @type {boolean}
+    @default null
+*/
     formnovalidate: {dataType: 'boolean'},
+
+/**
+    The target frame or window in which the form output should be rendered.
+    @type string}
+    @default null
+*/
     formtarget: null,
+
+/**
+    A string indicating the input type of the component's element.
+    @type {string}
+    @default "button"
+*/
     type: {value: 'button'},
+
+/**
+    The name associated with the component's DOM element.
+    @type {string}
+    @default null
+*/
     name: null,
+
+/**
+    The value associated with the element.
+    @type {string}
+    @default null
+*/
     value: null
 });
-- 
cgit v1.2.3