sproutcore 1.5.0.rc.1 → 1.5.0.rc.2

data/lib/frameworks/sproutcore/frameworks/desktop/views/button.js

@@ -5,13 +5,39 @@
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
-// ..........................................................
-// CONSTANTS
-//
+/**
+  @static
+  @constant
+  @type String
+*/
 SC.TOGGLE_BEHAVIOR = 'toggle';
+
+/**
+  @static
+  @constant
+  @type String
+*/
 SC.PUSH_BEHAVIOR =   'push';
+
+/**
+  @static
+  @constant
+  @type String
+*/
 SC.TOGGLE_ON_BEHAVIOR = 'on';
+
+/**
+  @static
+  @constant
+  @type String
+*/
 SC.TOGGLE_OFF_BEHAVIOR = 'off';
+
+/**
+  @static
+  @constant
+  @type String
+*/
 SC.HOLD_BEHAVIOR = 'hold';
 
 /** @class
@@ -34,10 +60,20 @@ SC.ButtonView = SC.View.extend(SC.Control,
 /** @scope SC.ButtonView.prototype */ {
 
   /**
-    The HTML representation of SC.ButtonView contains the 'sc-button-view'
-    class.
+    Tied to the isEnabled state
+    
+    @type Boolean
+    @default YES
+  */
+  acceptsFirstResponder: function() {
+    if(!SC.SAFARI_FOCUS_BEHAVIOR) return this.get('isEnabled');
+    else return NO;
+  }.property('isEnabled'),
 
-    @property {Array}
+  /**
+    @type Array
+    @default ['sc-button-view']
+    @see SC.View#classNames
   */
   classNames: ['sc-button-view'],
 
@@ -45,12 +81,14 @@ SC.ButtonView = SC.View.extend(SC.Control,
     The theme to apply to the button. By default, a subtheme with the name of
     'square' is created for backwards-compatibility.
 
-    @property {String}
+    @type String
+    @default 'square'
   */
   themeName: 'square',
 
+
   // ..........................................................
-  // VALUE PROPERTIES
+  // Value Handling
   // 
   
   /**
@@ -65,50 +103,52 @@ SC.ButtonView = SC.View.extend(SC.Control,
     YES or NO, the button will do its best to convert a value to an 
     appropriate state:
   
-    - null, false, 0  -> isSelected = false
-    - any other single value -> isSelected = true
-    - array -> if all values are the same state: that state.  otherwise MIXED.
+      - null, false, 0  -> isSelected = false
+      - any other single value -> isSelected = true
+      - array -> if all values are the same state: that state.  otherwise MIXED.
     
-    @property {Object}
+    @type Object
+    @default null
   */  
   value: null,
 
   /**
     Value of a selected toggle button.
-  
-    for a toggle button, set this to any object value you want.  The button
-    will be selected if the value property equals the targetValue.  If the
+    
+    For a toggle button, set this to any object value you want. The button
+    will be selected if the value property equals the targetValue. If the
     value is an array of multiple items that contains the targetValue, then
     the button will be set to a mixed state.
-
+    
     default is YES
     
-    @property {Object}
+    @type Boolean|Object
+    @default YES
   */
   toggleOnValue: YES,
 
   /**
     Value of an unselected toggle button.
-  
+    
     For a toggle button, set this to any object value you want.  When the
     user toggle's the button off, the value of the button will be set to this
     value.
-  
-    default is NO 
-  
-    @property {Object}
+    
+    @type Boolean|Object
+    @default NO
   */
   toggleOffValue: NO,
 
 
   // ..........................................................
-  // TITLE 
+  // Title Handling
   // 
   
   /**
     If YES, then the title will be localized.
     
-    @property {Boolean}
+    @type Boolean
+    @default NO
   */
   localize: NO,
   
@@ -118,24 +158,27 @@ SC.ButtonView = SC.View.extend(SC.Control,
   /**
     The button title.  If localize is YES, then this should be the localization key to display.  Otherwise, this will be the actual string displayed in the title.  This property is observable and bindable.
     
-    @property {String}
-  */  
-  title: '',
+    @type String
+    @default ""
+  */
+  title: "",
 
   /**
-    If you set this property, the title property will be updated automatically
+    If set, the title property will be updated automatically
     from the content using the key you specify.
     
-    @property {String}
+    @type String
+    @default null
   */
   contentTitleKey: null,
   
   /**
-    The button icon.  Set this to either a URL or a CSS class name (for 
-    spriting).  Note that if you pass a URL, it must contain at 
+    The button icon. Set this to either a URL or a CSS class name (for
+    spriting). Note that if you pass a URL, it must contain at
     least one slash to be detected as such.
     
-    @property {String}
+    @type String
+    @default null
   */
   icon: null,
 
@@ -143,24 +186,27 @@ SC.ButtonView = SC.View.extend(SC.Control,
     If you set this property, the icon will be updated automatically from the
     content using the key you specify.
     
-    @property {String}
+    @type String
+    @default null
   */
   contentIconKey: null,
 
   /**
-    If YES, button will attempt to display an ellipsis if the title cannot 
-    fit inside of the visible area.  This feature is not available on all
+    If YES, button will attempt to display an ellipsis if the title cannot
+    fit inside of the visible area. This feature is not available on all
     browsers.
     
-    @property {Boolean}
+    @type Boolean
+    @default YES
   */
   needsEllipsis: YES,
   
   /**
-    The computed display title.  This is generated by localizing the title 
-    property if necessary.
+    This is generated by localizing the title property if necessary.
     
-    @property {String}
+    @type String
+    @observes 'title'
+    @observes 'localize'
   */
   displayTitle: function() {
     var ret = this.get('title');
@@ -170,10 +216,12 @@ SC.ButtonView = SC.View.extend(SC.Control,
   /**
     The key equivalent that should trigger this button on the page.
     
-    @property {String}
+    @type String
+    @default null
   */
   keyEquivalent: null,
 
+
   // ..........................................................
   // BEHAVIOR
   // 
@@ -182,18 +230,20 @@ SC.ButtonView = SC.View.extend(SC.Control,
     The behavioral mode of this button.
 
     Possible values are:
-    - *SC.PUSH_BEHAVIOR* Pressing the button will trigger an action tied to the
-      button. Does not change the value of the button.
-    - *SC.TOGGLE_BEHAVIOR* Pressing the button will invert the current value of
-      the button. If the button has a mixed value, it will be set to true.
-    - *SC.TOGGLE_ON_BEHAVIOR* Pressing the button will set the current state to
-      true no matter the previous value.
-    - *SC.TOGGLE_OFF_BEHAVIOR* Pressing the button will set the current state to
-      false no matter the previous value.
-    - *SC.HOLD_BEHAVIOR* Pressing the button will cause the action to repeat at a
-      regular interval specifed by 'holdInterval'
-
-    @property {String}
+
+      - *SC.PUSH_BEHAVIOR* Pressing the button will trigger an action tied to the
+        button. Does not change the value of the button.
+      - *SC.TOGGLE_BEHAVIOR* Pressing the button will invert the current value of
+        the button. If the button has a mixed value, it will be set to true.
+      - *SC.TOGGLE_ON_BEHAVIOR* Pressing the button will set the current state to
+        true no matter the previous value.
+      - *SC.TOGGLE_OFF_BEHAVIOR* Pressing the button will set the current state to
+        false no matter the previous value.
+      - *SC.HOLD_BEHAVIOR* Pressing the button will cause the action to repeat at a
+        regular interval specifed by 'holdInterval'
+
+    @type String
+    @default SC.PUSH_BEHAVIOR
   */
   buttonBehavior: SC.PUSH_BEHAVIOR,
 
@@ -201,7 +251,8 @@ SC.ButtonView = SC.View.extend(SC.Control,
     If buttonBehavior is SC.HOLD_BEHAVIOR, this specifies, in milliseconds,
     how often to trigger the action. Ignored for other behaviors.
 
-    @property {Number}
+    @type Number
+    @default 100
   */
   holdInterval: 100,
 
@@ -211,7 +262,8 @@ SC.ButtonView = SC.View.extend(SC.Control,
     This is the same as setting the keyEquivalent to 'return'.  This will also
     apply the "def" classname to the button.
 
-    @property {Boolean}
+    @type Boolean
+    @default NO
   */
   isDefault: NO,
   isDefaultBindingDefault: SC.Binding.oneWay().bool(),
@@ -220,7 +272,8 @@ SC.ButtonView = SC.View.extend(SC.Control,
     If YES, then this button will be triggered when you hit escape.
     This is the same as setting the keyEquivalent to 'escape'.
 
-    @property {Boolean}
+    @type Boolean
+    @default NO
   */
   isCancel: NO,
   isCancelBindingDefault: SC.Binding.oneWay().bool(),
@@ -242,7 +295,8 @@ SC.ButtonView = SC.View.extend(SC.Control,
     clicked.  It is generally better to use the target/action approach and
     to implement your code in a controller of some type.
 
-    @property {String}
+    @type String
+    @default null
   */
   action: null,
 
@@ -254,52 +308,44 @@ SC.ButtonView = SC.View.extend(SC.Control,
     null, then the button will search the responder chain for a view that
     implements the action when the button is pressed instead.
 
-    @property {Object}
+    @type Object
+    @default null
   */
   target: null,
 
-  /**
-    If YES, use a focus ring.
-
-    TODO: When is this property ever changed? Is this redundant with
+  /*
+    TODO When is this property ever changed? Is this redundant with
     render delegates since it can now be turned on on a theme-by-theme
     basis? --TD
+  */
+  /**
+    If YES, use a focus ring.
 
-    @property {Boolean}
+    @type Boolean
+    @default NO
   */
   supportFocusRing: NO,
 
-  //
+  // ..........................................................
   // Auto Resize Support
+  // 
+  //
   // These properties are provided so that SC.AutoResize can be mixed in
   // to enable automatic resizing of the button.
   //
-  /**
-    SC.ButtonView supports automatic resizing.
 
-    @private
-    @property
-  */
+  /** @private */
   supportsAutoResize: YES,
 
-  /**
-    The layer for autoresizing buttons is the button layer itself.
-
-    TODO: get this from the render delegate so other elements may be used.
-
-    @private
-    @property
+  /*
+    TODO get this from the render delegate so other elements may be used.
   */
+  /** @private */
   autoResizeLayer: function() {
     return this.get('layer');
   }.property('layer').cacheable(),
 
-  /**
-    The text to be used to automatically resize the view: the displayTitle.
-
-    @private
-    @property
-  */
+  /** @private */
   autoResizeText: function() {
     return this.get('displayTitle');
   }.property('displayTitle').cacheable(),
@@ -312,7 +358,7 @@ SC.ButtonView = SC.View.extend(SC.Control,
     to 10.
 
     @default 10
-    @property
+    @type Number
   */
   autoResizePadding: SC.propertyFromRenderDelegate('autoResizePadding', 10),
 
@@ -330,7 +376,7 @@ SC.ButtonView = SC.View.extend(SC.Control,
     Does nothing if the button is disabled.
 
     @param {Event} evt
-    @returns {Boolean} success/failure of the request
+    @returns {Boolean} YES if successful, NO otherwise
   */
   triggerActionAfterDelay: function(evt) {
     // If this button is disabled, we have nothing to do
@@ -365,6 +411,9 @@ SC.ButtonView = SC.View.extend(SC.Control,
   */
   didTriggerAction: function() {},
 
+  /*
+    TODO Why is this not set by the theme? --TD
+  */
   /**
     The minimum width the button title should consume.  This property is used
     when generating the HTML styling for the title itself.  The default
@@ -374,15 +423,16 @@ SC.ButtonView = SC.View.extend(SC.Control,
     Note that the title width does not exactly match the width of the button
     itself.  Extra padding added by the theme can impact the final total
     size.
-    
-    TODO: Why is this not set by the theme? --TD
 
-    @property {Number}
+    @type Number
+    @default 80
   */
   titleMinWidth: 80,
 
+
   // ................................................................
   // INTERNAL SUPPORT
+  //
 
   /** @private - save keyEquivalent for later use */
   init: function() {
@@ -398,11 +448,15 @@ SC.ButtonView = SC.View.extend(SC.Control,
 
     // if value is not null, update isSelected to match value.  If value is
     // null, we assume you may be using isSelected only.  
-    if (!SC.none(this.get('value'))) this._button_valueDidChange();  
+    if (!SC.none(this.get('value'))) this._button_valueDidChange();
   },
 
   /**
     The WAI-ARIA role of the button.
+    
+    @type String
+    @default 'button'
+    @readOnly
   */
   ariaRole: 'button',
 
@@ -410,11 +464,15 @@ SC.ButtonView = SC.View.extend(SC.Control,
   // isCancel and isDefault also cause a refresh but this is implemented as
   // a separate observer (see below)
 
-  /** @private
+  /**
     The following properties affect how SC.ButtonView is rendered, and will
     cause the view to be rerendered if they change.
     
-    @property {Array}
+    @type Array
+    @default [
+      'icon', 'displayTitle', 'value', 'displayToolTip', 'isDefault', 'isCancel', 
+      'escapeHTML', 'needsEllipsis', 'hint', 'titleMinWidth', 'supportFocusRing'
+    ]
   */
   displayProperties: [
     'icon', 'displayTitle', 'value', 'displayToolTip', 'isDefault', 'isCancel', 
@@ -428,16 +486,17 @@ SC.ButtonView = SC.View.extend(SC.Control,
     In this case, the 'button' property will be retrieved from the theme and
     set to the render delegate of this view.
     
-    @property {String}
+    @type String
+    @default 'buttonRenderDelegate'
   */
   renderDelegateName: 'buttonRenderDelegate',
 
   /**
-    Updates the value, title, and icon keys based on the content object, if 
+    Updates the value, title, and icon keys based on the content object, if
     set.
     
-    @property {Object} target the target of the object that changed
-    @property {String} key name of property that changed
+    @type {Object} target the target of the object that changed
+    @type {String} key name of property that changed
     @returns {SC.ButtonView} receiver
   */
   contentPropertyDidChange: function(target, key) {
@@ -540,7 +599,7 @@ SC.ButtonView = SC.View.extend(SC.Control,
     return state ;
   },
 
-    /** @private
+  /** @private
     Whenever the button value changes, update the selected state to match.
   */
   _button_valueDidChange: function() {
@@ -573,7 +632,7 @@ SC.ButtonView = SC.View.extend(SC.Control,
     keyEquivalent property to 'return'. This cached value is used to restore
     the keyEquivalent property if isDefault is set back to NO.
     
-    @property {String}
+    @type String
   */
   _defaultKeyEquivalent: null,
 
@@ -616,7 +675,7 @@ SC.ButtonView = SC.View.extend(SC.Control,
       }
     }
 
-    return YES ;
+    return YES;
   },
 
   /** @private
@@ -654,6 +713,7 @@ SC.ButtonView = SC.View.extend(SC.Control,
     return YES ;
   },
 
+  /** @private */
   touchStart: function(touch){
     var buttonBehavior = this.get('buttonBehavior');
 
@@ -676,6 +736,7 @@ SC.ButtonView = SC.View.extend(SC.Control,
     return YES;
   },
 
+  /** @private */
   touchesDragged: function(evt, touches) {
     if (!this.touchIsInBoundary(evt)) {
       if (!this._touch_exited) this.set('isActive', NO);
@@ -689,6 +750,7 @@ SC.ButtonView = SC.View.extend(SC.Control,
     return YES;
   },
 
+  /** @private */
   touchEnd: function(touch){
     this._touch_exited = NO;
     this.set('isActive', NO); // track independently in case isEnabled has changed
@@ -703,7 +765,6 @@ SC.ButtonView = SC.View.extend(SC.Control,
     return YES ;
   },
 
-
   /** @private */
   keyDown: function(evt) {
     // handle tab key
@@ -720,12 +781,13 @@ SC.ButtonView = SC.View.extend(SC.Control,
     return NO;
   },
 
-  /** @private  Perform an action based on the behavior of the button.
+  /** @private
+    Perform an action based on the behavior of the button.
 
-   - toggle behavior: switch to on/off state
-   - on behavior: turn on.
-   - off behavior: turn off.
-   - otherwise: invoke target/action
+     - toggle behavior: switch to on/off state
+     - on behavior: turn on.
+     - off behavior: turn off.
+     - otherwise: invoke target/action
   */
   _action: function(evt, skipHoldRepeat) {
     switch(this.get('buttonBehavior')) {
@@ -795,8 +857,7 @@ SC.ButtonView = SC.View.extend(SC.Control,
   },
 
   /** @private */
-  _hasLegacyActionHandler: function()
-  {
+  _hasLegacyActionHandler: function() {
     var action = this.get('action');
     if (action && (SC.typeOf(action) === SC.T_FUNCTION)) return true;
     if (action && (SC.typeOf(action) === SC.T_STRING) && (action.indexOf('.') != -1)) return true;
@@ -816,12 +877,7 @@ SC.ButtonView = SC.View.extend(SC.Control,
     }
   },
 
-  /** tied to the isEnabled state */
-  acceptsFirstResponder: function() {
-    if(!SC.SAFARI_FOCUS_BEHAVIOR) return this.get('isEnabled');
-    else return NO;
-  }.property('isEnabled'),
-
+  /** @private */
   willBecomeKeyResponderFrom: function(keyView) {
     // focus the text field.
     if (!this._isFocused) {
@@ -833,10 +889,12 @@ SC.ButtonView = SC.View.extend(SC.Control,
     }
   },
 
+  /** @private */
   willLoseKeyResponderTo: function(responder) {
     if (this._isFocused) this._isFocused = NO ;
   },
 
+  /** @private */
   didAppendToDocument: function() {
     if(parseInt(SC.browser.msie, 0)===7 && this.get('useStaticLayout')){
       var layout = this.get('layout'),

data/lib/frameworks/sproutcore/frameworks/desktop/views/checkbox.js

@@ -22,32 +22,61 @@
   @since SproutCore 1.0
 */
 SC.CheckboxView = SC.ButtonView.extend(SC.StaticLayout,
-  /** @scope SC.CheckboxView.prototype */ {
+/** @scope SC.CheckboxView.prototype */ {
 
+  /**
+    @type Array
+    @default ['sc-checkbox-view', 'sc-checkbox-control']
+    @see SC.View#classNames
+  */
   classNames: ['sc-checkbox-view', 'sc-checkbox-control'],
+
+  /**
+    @type String
+    @default 'label'
+    @see SC.View#tagName
+  */
   tagName: 'label',
 
   /**
-    The WAI-ARIA role of checkbox. This property's value should not be
-    changed.
+    The WAI-ARIA role of checkbox.
 
-    @property {String}
+    @type String
+    @readOnly
   */
   ariaRole: 'checkbox',
 
   // no special theme for Checkbox; button defaults to 'square', so we have to stop that.
   themeName: null,
+  
+  /**
+    @type String
+    @default 'checkboxRenderDelegate'
+  */
   renderDelegateName: 'checkboxRenderDelegate',
 
-  /* Ellipsis is disabled by default to allow multiline text */
+  /**
+    Ellipsis is disabled by default to allow multiline text
+    
+    @type Boolean
+    @default NO
+  */
   needsEllipsis: NO,
   
+  /**
+    YES if `isEnabled` is YES, NO otherwise
+    
+    @type Boolean
+    @default NO
+    @observes isEnabled
+  */
   acceptsFirstResponder: function() {
     if(!SC.SAFARI_FOCUS_BEHAVIOR) return this.get('isEnabled');
     else return NO;
   }.property('isEnabled'),
   
   
+  /** @private */
   mouseDown: function(evt) {
     if(!this.get('isEnabled')) return YES;
     this.set('isActive', YES);
@@ -58,6 +87,7 @@ SC.CheckboxView = SC.ButtonView.extend(SC.StaticLayout,
     return YES;
   },
   
+  /** @private */
   mouseUp: function(evt) {
     this.set('isActive', NO);
     this._isMouseDown = NO;
@@ -77,10 +107,12 @@ SC.CheckboxView = SC.ButtonView.extend(SC.StaticLayout,
   },
   
   
+  /** @private */
   touchStart: function(evt) {
     return this.mouseDown(evt);
   },
   
+  /** @private */
   touchEnd: function(evt) {
     return this.mouseUp(evt);
   }