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

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

@@ -4,6 +4,8 @@
 //            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
+
+
 /** @class
 
   A RadioView is used to create a group of radio buttons.  The user can use
@@ -15,36 +17,36 @@
   The radio buttons themselves are designed to be styled using CSS classes with
   the following structure:
   
-  <label class="sc-radio-button">
-  <img class="button" src="some_image.gif"/>
-  <input type="radio" name="<sc-guid>" value=""/>
-  <span class="sc-button-label">Label for button1</span>
-  </label>
+      <label class="sc-radio-button">
+        <img class="button" src="some_image.gif"/>
+        <input type="radio" name="<sc-guid>" value=""/>
+        <span class="sc-button-label">Label for button1</span>
+      </label>
   
   Setting up a RadioView accepts a number of properties, for example:
-  {
-    items: [{ title: "Red", 
-              value: "red", 
-              enabled: YES, 
-              icon: "button_red" },
-            { title: "Green", 
-              value: "green", 
-              enabled: YES, 
-              icon: 'button_green' }],
-    value: 'red',
-    itemTitleKey: 'title',
-    itemValueKey: 'value',
-    itemIconKey: 'icon',
-    itemIsEnabledKey: 'enabled',
-    isEnabled: YES,
-    layoutDirection: SC.LAYOUT_HORIZONTAL
-  }
-  
-  Default layoutDirection is vertical. 
-  Default isEnabled is YES.
   
-  The value property can be either a string, as above, or an array of strings
-  for pre-checking multiple values.
+      radio: SC.RadioView.design({
+        items: [
+          { 
+            title: "Red",
+            value: "red",
+            enabled: YES,
+            icon: "button_red"
+          },{
+            title: "Green",
+            value: "green",
+            enabled: YES,
+            icon: 'button_green'
+          }
+        ],
+        value: 'red',
+        itemTitleKey: 'title',
+        itemValueKey: 'value',
+        itemIconKey: 'icon',
+        itemIsEnabledKey: 'enabled',
+        isEnabled: YES,
+        layoutDirection: SC.LAYOUT_HORIZONTAL
+      })
   
   The items array can contain either strings, or as in the example above a 
   hash. When using a hash, make sure to also specify the itemTitleKey
@@ -52,33 +54,67 @@
   itemIconKey if you are using icons radio buttons. The individual items 
   enabled property is YES by default, and the icon is optional.
   
-  @extends SC.FieldView
+  @extends SC.View
+  @extends SC.Control
   @since SproutCore 1.0
 */
 SC.RadioView = SC.View.extend(SC.Control,
-/** @scope SC.RadioView.prototype */
-{
+/** @scope SC.RadioView.prototype */{
+
+  /**
+    @field
+    @type Boolean
+    @default YES
+    @observes isEnabled
+  */
+  acceptsFirstResponder: function() {
+    if(!SC.SAFARI_FOCUS_BEHAVIOR) return this.get('isEnabled');
+    else return NO;
+  }.property('isEnabled'),
 
-  // HTML design options
+  /**
+    @type Array
+    @default ['sc-radio-view']
+    @see SC.View#classNames
+  */
   classNames: ['sc-radio-view'],
 
   /**
-    The WAI-ARIA role for a group of radio buttons. This property's value
-    should not be changed.
+    The WAI-ARIA role for a group of radio buttons.
 
-    @property {String}
+    @type String
+    @default 'radiogroup'
+    @readOnly
   */
   ariaRole: 'radiogroup',
 
+  /** 
+    @type Array
+    @default ['displayItems', 'isEnabled', 'layoutDirection']
+    @see SC.View#displayProperties
+  */
+  displayProperties: ['displayItems', 'isEnabled', 'layoutDirection'],
+  
+  /**
+    @type String
+    @default 'radioGroupRenderDelegate'
+  */
+  renderDelegateName: 'radioGroupRenderDelegate',
+
+  // ..........................................................
+  // Properties
+  // 
+  
   /**
-  If items property is a hash, specify which property will function as
-  the ariaLabeledBy with this itemAriaLabeledByKey property.ariaLabeledBy is used
-  as the WAI-ARIA attribute for the radio view. This property is assigned to
-  'aria-labelledby' attribute, which defines a string value that labels the
-  element. Used to support voiceover.  It should be assigned a non-empty string,
-  if the 'aria-labelledby' attribute has to be set for the element.
-
-    @property {String}
+    If items property is a hash, specify which property will function as
+    the ariaLabeledBy with this itemAriaLabeledByKey property.ariaLabeledBy is used
+    as the WAI-ARIA attribute for the radio view. This property is assigned to
+    'aria-labelledby' attribute, which defines a string value that labels the
+    element. Used to support voiceover.  It should be assigned a non-empty string,
+    if the 'aria-labelledby' attribute has to be set for the element.
+
+    @type String
+    @default null
   */
   itemAriaLabeledByKey: null,
 
@@ -90,7 +126,8 @@ SC.RadioView = SC.View.extend(SC.Control,
     element. Used to support voiceover.  It should be assigned a non-empty string,
     if the 'aria-label' attribute has to be set for the element.
 
-    @property {String}
+    @type String
+    @default null
   */
   itemAriaLabelKey: null,
 
@@ -98,27 +135,45 @@ SC.RadioView = SC.View.extend(SC.Control,
     The value of the currently selected item, and which will be checked in the 
     UI. This can be either a string or an array with strings for checking 
     multiple values.
+    
+    @type Object|String
+    @default null
   */
   value: null,
 
   /**
-    This property indicates how the radio buttons are arranged.
+    This property indicates how the radio buttons are arranged. Possible values:
+    
+      - SC.LAYOUT_VERTICAL
+      - SC.LAYOUT_HORIZONTAL
+    
+    @type String
+    @default SC.LAYOUT_VERTICAL
   */
   layoutDirection: SC.LAYOUT_VERTICAL,
 
-  // escape the HTML in label text
+  /**
+    @type Boolean
+    @default YES
+  */
   escapeHTML: YES,
 
   /** 
     The items property can be either an array with strings, or a
     hash. When using a hash, make sure to also specify the appropriate
     itemTitleKey, itemValueKey, itemIsEnabledKey and itemIconKey.
+    
+    @type Array
+    @default []
   */
   items: [],
 
   /** 
     If items property is a hash, specify which property will function as
     the title with this itemTitleKey property.
+    
+    @type String
+    @default null
   */
   itemTitleKey: null,
   
@@ -128,7 +183,7 @@ SC.RadioView = SC.View.extend(SC.Control,
     layoutDirection is set to SC.LAYOUT_HORIONZTAL and can be used to override
     the default value provided by the framework or theme CSS.
     
-    @property {String}
+    @type String
     @default null
   */
   itemWidthKey: null,
@@ -136,22 +191,31 @@ SC.RadioView = SC.View.extend(SC.Control,
   /** 
     If items property is a hash, specify which property will function as
     the value with this itemValueKey property.
+    
+    @type String
+    @default null
   */
   itemValueKey: null,
 
   /** 
     If items property is a hash, specify which property will function as
     the value with this itemIsEnabledKey property.
+    
+    @type String
+    @default null
   */
   itemIsEnabledKey: null,
 
   /** 
     If items property is a hash, specify which property will function as
     the value with this itemIconKey property.
+    
+    @type String
+    @default null
   */
   itemIconKey: null,
 
-  /** 
+  /**  @private
     If the items array itself changes, add/remove observer on item... 
   */
   itemsDidChange: function() {
@@ -165,7 +229,7 @@ SC.RadioView = SC.View.extend(SC.Control,
     this.itemContentDidChange();
   }.observes('items'),
 
-  /** 
+  /** @private
     Invoked whenever the item array or an item in the array is changed.
     This method will regenerate the list of items.
   */
@@ -179,11 +243,6 @@ SC.RadioView = SC.View.extend(SC.Control,
   // ..........................................................
   // PRIVATE SUPPORT
   // 
-  /** 
-    The display properties for radio buttons are the value and _displayItems.
-  */
-  displayProperties: ['displayItems', 'isEnabled', 'layoutDirection'],
-  renderDelegateName: 'radioGroupRenderDelegate',
 
   /** @private
     Data Sources for radioRenderDelegates, as required by radioGroupRenderDelegate.
@@ -280,13 +339,7 @@ SC.RadioView = SC.View.extend(SC.Control,
     return ret; // done!
   }.property('isEnabled', 'value', 'items', 'itemTitleKey', 'itemWidthKey', 'itemValueKey', 'itemIsEnabledKey', 'localize', 'itemIconKey','itemAriaLabeledByKey', 'itemAriaLabelKey').cacheable(),
 
-
-  acceptsFirstResponder: function() {
-    if(!SC.SAFARI_FOCUS_BEHAVIOR) return this.get('isEnabled');
-    else return NO;
-  }.property('isEnabled'),
-  
-  /**
+  /** @private
     If the user clicks on of the items mark it as active on mouseDown unless
     is disabled.
 
@@ -312,7 +365,7 @@ SC.RadioView = SC.View.extend(SC.Control,
     return YES;
   },
 
-  /**
+  /** @private
     If we have a radio element that was clicked on previously, make sure we
     remove the active state. Then update the value if the item clicked is 
     enabled.
@@ -338,11 +391,14 @@ SC.RadioView = SC.View.extend(SC.Control,
     }
   },
 
+  /** @private */
   touchStart: function(evt) {
     return this.mouseDown(evt);
   },
 
+  /** @private */
   touchEnd: function(evt) {
     return this.mouseUp(evt);
   }
+
 });

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

@@ -13,7 +13,7 @@
   optionally choose the kind of animation used to transition the two scenes 
   as well if supported on the web browser.
   
-  h1. Using The View
+  # Using SC.SceneView
   
   To setup the scene view, you should define the 'scenes' property with an 
   array of scene names.  These will be the properties on the scene view that
@@ -26,11 +26,11 @@
   is visible on screen.  Otherwise, it will simply make the new scene view 
   the current content view and that's it.
 
-  @extends SC.View
+  @extends SC.ContainerView
   @since SproutCore 1.0
 */
 SC.SceneView = SC.ContainerView.extend(
-  /** @scope SC.SceneView.prototype */ {
+/** @scope SC.SceneView.prototype */ {
 
   /**
     Array of scene names.  Scenes will slide on and off screen in the order
@@ -38,10 +38,8 @@ SC.SceneView = SC.ContainerView.extend(
     2 to a scene at index 1, the scenes will animation backwards.  If you
     shift to a scene at index 3, the scenes will animate forwards.
     
-    The default scenes defined are 'master' and 'detail'.  You can replace or 
-    augment this array as you like.
-    
-    @property {Array}
+    @type Array
+    @default ['master', 'detail']
   */
   scenes: ['master', 'detail'],
 
@@ -50,21 +48,26 @@ SC.SceneView = SC.ContainerView.extend(
     scene view to transition to the new scene.  If you set this property to 
     null, an empty string, or a non-existant scene, then the scene will appear
     empty.
+    
+    @type String
+    @default null
   */
   nowShowing: null,
   
   /**
     Speed of transition.  Should be expressed in msec.
+    
+    @type Number
+    @default 200
   */
   transitionDuration: 200,
   
+  /** @private */
   _state: 'NO_VIEW', // no view
 
   /** @private
-  
     Whenever called to change the content, save the nowShowing state and 
     then animate in by adjusting the layout.
-    
   */
   replaceContent: function(content) {
     if (content && this._state===this.READY) this.animateScene(content);
@@ -73,7 +76,6 @@ SC.SceneView = SC.ContainerView.extend(
   },
 
   /** @private
-  
     Invoked whenever we just need to swap the scenes without playing an
     animation.
   */
@@ -102,7 +104,6 @@ SC.SceneView = SC.ContainerView.extend(
   },
 
   /** @private
-  
     Invoked whenever we need to animate in the new scene.
   */
   animateScene: function(newContent) {
@@ -143,7 +144,8 @@ SC.SceneView = SC.ContainerView.extend(
     this.tick();
   },
 
-  /** @private - called while the animation runs.  Compute the new layout for
+  /** @private
+    Called while the animation runs.  Compute the new layout for
     the left and right views based on the portion completed.  When we finish
     call replaceScene().
   */
@@ -192,13 +194,18 @@ SC.SceneView = SC.ContainerView.extend(
   },
   
 
-  // states for view animation
+  /** @private */
   NO_VIEW: 'NO_VIEW',
+  
+  /** @private */
   ANIMATING: 'ANIMATING',
+  
+  /** @private */
   READY: 'READY',
 
-  /** @private - standard layout assigned to views at rest */
+  /** @private
+    Standard layout assigned to views at rest
+  */
   STANDARD_LAYOUT: { top: 0, left: 0, bottom: 0, right: 0 }
-  
-  
+
 });