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

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

@@ -15,34 +15,25 @@
   
   By default the Date Field View show Date only, but if you need to show the Time do:
   
-  {{{
-    dateAndTime: Shared.DateFieldView.design({
-      showTime: YES,
-      valueBinding: '...'
-    }),
-  }}}
+      dateAndTime: Shared.DateFieldView.design({
+        showTime: YES,
+        valueBinding: '...'
+      }),
   
-  and if you only need to show time: 
+  and if you only need to show time:
   
-  {{{
-    timeOnly: Shared.DateFieldView.design({
-      showTime: YES,
-      showDate: NO,
-      valueBinding: '...'
-    })
-  }}}
-  
-  The default format are:
-  - formatTime: '%I:%M %p',
-  - formatDate: '%d/%m/%Y',
-  - formatDateTime: '%d/%m/%Y %I:%M %p',
+      timeOnly: Shared.DateFieldView.design({
+        showTime: YES,
+        showDate: NO,
+        valueBinding: '...'
+      })
   
   Example usage with special format:
-
-  specialDate: Shared.DateFieldView.design({
-    formatDate: '%d %b of %Y',
-    valueBinding: '...'
-  }),
+  
+      specialDate: Shared.DateFieldView.design({
+        formatDate: '%d %b of %Y',
+        valueBinding: '...'
+      }),
   
   You can override these format as you like, but has some limitations,
   actually only support these KEY from SC.DateTime:
@@ -56,29 +47,57 @@
   @author Juan Pablo Goldfinger
 */
 SC.DateFieldView = SC.TextFieldView.extend(
-/** @scope SC.DateFieldView.prototype */
-{
+/** @scope SC.DateFieldView.prototype */ {
 
+  /**
+    @type String
+    @default null
+  */
   value: null,
   
-  // Default Behaviour
+  /**
+    @type Boolean
+    @default YES
+  */
   showDate: YES,
+  
+  /**
+    @type Boolean
+    @default NO
+  */
   showTime: NO,
   
-  // Default formats to choose depending of the behaviour.
+  /**
+    @type String
+    @default '%I:%M %p'
+  */
   formatTime: '%I:%M %p',
+  
+  /**
+    @type String
+    @default '%d/%m/%Y'
+  */
   formatDate: '%d/%m/%Y',
+  
+  /**
+    @type String
+    @default '%d/%m/%Y %I:%M %p'
+  */
   formatDateTime: '%d/%m/%Y %I:%M %p',
   
   // DateTime constants (with fixed width, like numbers or abbs with fixed length)
   // original: '%a %A %b %B %c %d %h %H %i %I %j %m %M %p %S %U %W %x %X %y %Y %Z %%'.w(),
   // NOTE: I think that %a and %b areb't useful because is more adecuato to represente day
   // with 1..31 without zeros at start, but causes the lenght not to be fixed)
+
+  /** @private*/
   _dtConstants: '%a %b %d %H %I %j %m %M %p %S %U %W %y %Y'.w(),
   // Width constants for each representation %@.
+  
+  /** @private */
   _wtConstants: [3,3,2,2,2,3,2,2,2,2,2,2,2,4],
   
-  // PRIVATE ATTRIBUTES
+  /** @private */
   activeSelection: 0,
 
   /*
@@ -100,8 +119,10 @@ SC.DateFieldView = SC.TextFieldView.extend(
   /**
     The current format to apply for Validator and to show.
     
-    @property
-    @type {String}
+    @field
+    @type String
+    @observes showTime
+    @observes showDate
   */
   format: function() {
     var st = this.get('showTime');
@@ -114,8 +135,9 @@ SC.DateFieldView = SC.TextFieldView.extend(
   /**
     The current validator to format the Date to the input field and viceversa.
     
-    @property
-    @type {SC.Validator.DateTime}
+    @field
+    @type SC.Validator.DateTime
+    @observes format
   */
   validator: function() {
     return SC.Validator.DateTime.extend({ format: this.get('format') });
@@ -124,8 +146,8 @@ SC.DateFieldView = SC.TextFieldView.extend(
   /**
     Array of Key/TextSelection found for the current format.
     
-    @property
-    @type {SC.Array}
+    @field
+    @type SC.Array
   */  
   tabsSelections: function() {
     var arr = [];
@@ -164,7 +186,6 @@ SC.DateFieldView = SC.TextFieldView.extend(
   
   /** @private
     If the activeSelection changes or the value changes, update the "TextSelection" to show accordingly.
-   
   */
   updateTextSelecitonObserver: function() {
     var as = this.get('activeSelection');
@@ -176,7 +197,6 @@ SC.DateFieldView = SC.TextFieldView.extend(
   
   /** @private
     Updates the value according the key.
-   
   */
   updateValue: function(key, upOrDown) {
     // 0 is DOWN - 1 is UP
@@ -207,19 +227,12 @@ SC.DateFieldView = SC.TextFieldView.extend(
     }*/
   },
 
-  /*_textField_fieldDidFocus: function(evt) {
-    SC.RunLoop.begin();
-    //console.log(evt);
-    //console.log(event);
-    //console.log(evt.originalEvent);
-    this.fieldDidFocus();
-    SC.RunLoop.end();
-  },*/
   
-  /////////////////////////
-  // KEY EVENTS SUPPORTS
-  /////////////////////////
+  // ..........................................................
+  // Key Event Support
+  // 
   
+  /** @private */
   keyDown: function(evt) {
     if (this.interpretKeyEvents(evt)) {
       evt.stop();
@@ -228,10 +241,12 @@ SC.DateFieldView = SC.TextFieldView.extend(
     return sc_super();
   },
   
+  /** @private */
   ctrl_a: function() {
     return YES;
   },
 
+  /** @private */
   moveUp: function(evt) {
     var as = this.get('activeSelection');
     var ts = this.get('tabsSelections');
@@ -239,6 +254,7 @@ SC.DateFieldView = SC.TextFieldView.extend(
     return YES;
   },
 
+  /** @private */
   moveDown: function(evt) {
     var as = this.get('activeSelection');
     var ts = this.get('tabsSelections');
@@ -246,10 +262,12 @@ SC.DateFieldView = SC.TextFieldView.extend(
     return YES;
   },
 
+  /** @private */
   insertText: function(evt) {
     return YES;
   },
 
+  /** @private */
   moveRight: function(evt) {
     var ts = this.get('tabsSelections');
     var ns = this.get('activeSelection') + 1;
@@ -260,6 +278,7 @@ SC.DateFieldView = SC.TextFieldView.extend(
     return YES;
   },
     
+  /** @private */
   moveLeft: function(evt) {
     var ts = this.get('tabsSelections');
     var ns = this.get('activeSelection') - 1;
@@ -270,6 +289,7 @@ SC.DateFieldView = SC.TextFieldView.extend(
     return YES;
   },
 
+  /** @private */
   insertTab: function(evt) {
     var ts = this.get('tabsSelections');
     var ns = this.get('activeSelection') + 1;
@@ -280,15 +300,17 @@ SC.DateFieldView = SC.TextFieldView.extend(
     return NO;
   },
 
+  /** @private */
   insertBacktab: function(evt) {
     var ns = this.get('activeSelection') - 1;
     if (ns !== -1) { 
       this.set('activeSelection', ns);
-      return YES;   
+      return YES;
     }
     return NO;
   },
 
+  /** @private */
   mouseUp: function(evt) {
     var ret = sc_super();
     var cs = this.get('selection');
@@ -308,10 +330,12 @@ SC.DateFieldView = SC.TextFieldView.extend(
     return ret;
   },
 
+  /** @private */
   deleteBackward: function(evt) {
     return YES;
   },
 
+  /** @private */
   deleteForward: function(evt) {
     return YES;
   }

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

@@ -11,50 +11,75 @@
   Disclosure triangle button. As a subclass of SC.ButtonView, this view
   takes a lot of the same properties as a button:
   
-  - isEnabled: whether disclosure triangle is clickable or not
-  - value: YES or NO (where YES implies expanded/open)
+    - isEnabled: whether disclosure triangle is clickable or not
+    - value: `YES` or `NO` (where `YES` implies expanded/open)
+  
+  A disclosure view also supports expanding and collapsing via
+  the keyboard.
   
   @extends SC.ButtonView
-  @since SproutCore
+  @since SproutCore 1.0
 */
 SC.DisclosureView = SC.ButtonView.extend(
 /** @scope SC.DisclosureView.prototype */ {
   
+  /**
+    @type Array
+    @default ['sc-disclosure-view']
+    @see SC.View#classNames
+  */
   classNames: ['sc-disclosure-view'],
 
+  /**
+    @type String
+    @default 'disclosureRenderDelegate'
+  */
   renderDelegateName: 'disclosureRenderDelegate',
 
+  /**
+    @type String
+    @default SC.TOGGLE_BEHAVIOR
+    @see SC.ButtonView#buttonBehavior
+  */
   buttonBehavior: SC.TOGGLE_BEHAVIOR,
   
   /**
     This is the value that will be set when the disclosure triangle is toggled
     open.
+    
+    @type Boolean
+    @default YES
   */
   toggleOnValue: YES,
   
   /**
     The value that will be set when the disclosure triangle is toggled closed.
+    
+    @type Boolean
+    @default YES
   */
   toggleOffValue: NO,
   
   /** @private */
-  valueBindingDefault: SC.Binding.bool() ,
+  valueBindingDefault: SC.Binding.bool(),
 
-  /**
-    Allows toggling of the value with the right and left arrow keys. 
+  /** @private
+
+    Allows toggling of the value with the right and left arrow keys.
     Extends the behavior inherted from SC.ButtonView.
     @param evt
   */
   keyDown: function(evt) {
-    if (evt.which === 37 || evt.which === 38) {  
+    if (evt.which === 37 || evt.which === 38) {
       this.set('value', this.get('toggleOffValue')) ;
       return YES;
     }
-    if (evt.which === 39 || evt.which === 40) {  
+
+    if (evt.which === 39 || evt.which === 40) {
       this.set('value', this.get('toggleOnValue')) ;
       return YES;
     }
     sc_super();
   }
-  
+
 });

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

@@ -4,27 +4,48 @@
 //            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
+
+/*
+  TODO revisit this to see if these classnames are usable
+*/
+
 /** @class
 
   Implements a customized file input by creating a standard file input in a
   transparent iframe over top of a SC.ButtonView.
   
-  // TODO: revisit this to see if these classnames are usable
   SC.FieldView uses the SC.Control mixin which will apply CSS 
   classnames when the state of the file view changes:
+  
     - active     when button is active
     - sel        when button is toggled to a selected state
   
   @extends SC.FieldView
-  @since SproutCore 1.0 
+  @since SproutCore 1.0
   @author Tyler Keating
 */
 SC.FileView = SC.FieldView.extend(
-/** @scope SC.FileView.prototype */
-{
+/** @scope SC.FileView.prototype */ {
+
+  /**
+    @type Array
+    @default ['sc-file-view']
+    @see SC.View#classNames
+  */
+  classNames: ['sc-file-view'],
+  
+  /** @private */
+  childViews: ['button', 'form'],
 
-  classNames: 'sc-file-view'.w(),
 
+  // ..........................................................
+  // Properties
+  // 
+
+  /**
+    @type Boolean
+    @default YES
+  */
   autoSubmit: YES,
 
   /**
@@ -39,12 +60,13 @@ SC.FileView = SC.FieldView.extend(
     here.  If you set a target, then the button will try to call the method
     on the target itself.
     
-    For legacy support, you can also set the action property to a function.  
+    For legacy support, you can also set the action property to a function.
     Doing so will cause the function itself to be called when the button is
     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 'uploadImage'
   */
   action: 'uploadImage',
   
@@ -56,20 +78,33 @@ SC.FileView = SC.FieldView.extend(
     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,
   
-  childViews: 'button form'.w(),
-  
+  /**
+    @type String
+    @default "Choose File"
+  */
+  title: "Choose File",
+
+
+  // ..........................................................
+  // Views
+  // 
+
+  /** @private */
   button: SC.ButtonView.design({
     title: 'Choose File',
     theme: 'capsule'
   }),
 
+  /** @private */
   form: SC.View.design({
     tagName: 'form',
     
+    /** @private */
     render: function(context, firstTime) {
       context.attr('method', 'post').attr('action', "javascript:;").attr('enctype', 'multipart/form-data');
       sc_super();
@@ -80,6 +115,7 @@ SC.FileView = SC.FieldView.extend(
     input: SC.View.design({
       tagName: 'input',
 
+      /** @private */
       render: function(context, firstTime) {
         context.attr('type', 'file').end();
         sc_super();
@@ -87,19 +123,20 @@ SC.FileView = SC.FieldView.extend(
     })
   }),
   
-  title: 'Choose File',
   
-  /** SC.FieldView **/
+  // ..........................................................
+  // FieldView Overrides
+  // 
   
-  /**
+  /** @private
     Since it is impossible to set the value of file inputs, don't attempt it.
-    
   */
   setFieldValue: function(newValue) {
     SC.Logger.log("SC.FileView: setFieldValue: %@ does nothing".fmt(newValue));
     //if (newValue) throw SC.$error('SC.FileView can not set the value of the file field');
   },
   
+  /** @private */
   fieldValueDidChange: function(partialChange) {
     sc_super();
     if (this.get('autoSubmit')) {

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

@@ -4,9 +4,6 @@
 //            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
-// ==========================================================================
-// SC.GridView
-// ==========================================================================
 
 require('views/list') ;
 
@@ -14,20 +11,34 @@ require('views/list') ;
 
   A grid view renders a collection of items in a grid of rows and columns.
 
-  @extends SC.CollectionView
-  @author    Charles Jolley  
+  @extends SC.ListView
+  @author Charles Jolley
   @version 1.0
 */
 SC.GridView = SC.ListView.extend(
 /** @scope SC.GridView.prototype */ {
-    classNames: ['sc-grid-view'],
+
+  /**
+    @type Array
+    @default ['sc-grid-view']
+    @see SC.View#classNames
+  */
+  classNames: ['sc-grid-view'],
   
+  /**
+    @type Hash
+    @default { left:0, right:0, top:0, bottom:0 }
+    @see SC.View#layout
+  */
   layout: { left:0, right:0, top:0, bottom:0 },
 
   /** 
     The common row height for grid items.
     
     The value should be an integer expressed in pixels.
+    
+    @type Number
+    @default 48
   */
   rowHeight: 48,
   
@@ -35,6 +46,9 @@ SC.GridView = SC.ListView.extend(
     The minimum column width for grid items.  Items will actually
     be laid out as needed to completely fill the space, but the minimum
     width of each item will be this value.
+    
+    @type Number
+    @default 64
   */
   columnWidth: 64,
 
@@ -42,9 +56,21 @@ SC.GridView = SC.ListView.extend(
     The default example item view will render text-based items.
     
     You can override this as you wish.
+    
+    @type SC.View
+    @default SC.LabelView
   */
   exampleView: SC.LabelView,
   
+  /**
+    Possible values:
+    
+      - SC.HORIZONTAL_ORIENTATION
+      - SC.VERTICAL_ORIENTATION
+    
+    @type String
+    @default SC.HORIZONTAL_ORIENTATION
+  */
   insertionOrientation: SC.HORIZONTAL_ORIENTATION,
   
   /** @private */
@@ -105,15 +131,18 @@ SC.GridView = SC.ListView.extend(
     return ret; 
   },
   
+  /**
+    @type SC.View
+  */
   insertionPointClass: SC.View.extend({
     classNames: ['grid-insertion-point'],
     
     render: function(context, firstTime) {
       if (firstTime) context.push('<span class="anchor"></span>') ;
     }
-
   }),
   
+  /** @private */
   showInsertionPoint: function(itemView, dropOperation) {
     if (!itemView) return ;
     
@@ -155,6 +184,7 @@ SC.GridView = SC.ListView.extend(
     
   },
     
+  /** @private */
   hideInsertionPoint: function() {
     var insertionPoint = this._insertionPointView ;
     if (insertionPoint) insertionPoint.removeFromParent() ;
@@ -165,7 +195,7 @@ SC.GridView = SC.ListView.extend(
     }
   },
   
-  // // We can do this much faster programatically using the rowHeight
+  /** @private */
   insertionIndexForLocation: function(loc, dropOperation) {  
     var f = this.get('frame'),
         sf = this.get('clippingFrame'),

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

@@ -44,9 +44,9 @@ SC.ImageButtonView = SC.ButtonView.extend(
 /** @scope SC.ImageButtonView.prototype */ {
 
   /**
-    Class names that will be applied to this view
-
-    @property {Array}
+    @type Array
+    @default ['sc-image-button-view']
+    @see SC.View#classNames
   */
   classNames: ['sc-image-button-view'],
 
@@ -54,23 +54,29 @@ SC.ImageButtonView = SC.ButtonView.extend(
     Unlike SC.ButtonView, SC.ImageButtonView does not have a default theme
     that needs to be applied for backwards compatibility.
 
-    @property {String}
+    @type String
+    @default null
   */
   themeName: null,
 
   /**
-    The name of the theme's SC.ImageButtonView render delegate.
-
-    @property {String}
+    @type String
+    @default 'imageButtonRenderDelegate'
   */
   renderDelegateName: 'imageButtonRenderDelegate',
   
+  /**
+    @type Array
+    @default ['image']
+  */
   displayProperties: ['image'],
 
   /**
     A class name that will be applied to the img tag of the button.
-
-    @property {String}
+    
+    @type String
+    @default null
   */
   image: null
+
 }) ;