sproutcore 0.9.2 → 0.9.3

data/frameworks/sproutcore/mixins/inline_editor_delegate.js

@@ -0,0 +1,72 @@
+// ========================================================================
+// SproutCore
+// copyright 2006-2008 Sprout Systems, Inc.
+// ========================================================================
+
+/**
+  @namespace
+  
+  The inline editor delegate receives notifications from the inline text
+  editor before, during, and after the user completes inline editing.
+  
+  The inline editor delegate is used by views that work with the inline
+  editor.  You may need to implement this protocol if you want to
+  use the inline editor in your own custom views.
+  
+  @since SproutCore 1.0
+*/
+SC.InlineEditorDelegate = {
+  
+    /**
+      Called just before the inline edit displays itself but after it has been 
+      configured for display.  
+      
+      You can use this method to make last minute changes to the display of 
+      the inline editor or to collect its value.
+      
+      @param inlineEditor {SC.InlineTextFieldView} The inline editor.
+      @returns {void}
+    */
+    inlineEditorWillBeginEditing: function(inlineEditor) {},
+
+    /**
+      Called just after an inline editor displays itself.
+      
+      You can use this method to perform any hiding or other view changes
+      you need to perform on your own view to make room for the new editor.
+      
+      Note tht editors are placed over the top of views in the page, not 
+      inside of them from a DOM perspective.
+      
+      @param inlineEditor {SC.InlineTextFieldView} The inline editor.
+      @returns {void}
+    */
+    inlineEditorDidBeginEditing: function(inlineEditor) {},
+    
+    /**
+      Called just before an inline editor tries to end editing and hide 
+      itself.
+      
+      You can use this method to control whether the inline editor will
+      actually be allowed to end editing.  For example, you might disallow
+      the editor to end editing if the new value fails validation.
+      
+      @param inlineEditor {SC.InlineTextFieldView} the inline editor
+      @param finalValue {Object} the final value
+      @returns {Boolean} YES to allow the editor to end editing.
+    */
+    inlineEditorShouldEndEditing: function(inlineEditor, finalValue) {
+      return YES ;
+    },
+    
+    /**
+      Called just after the inline editor has ended editing. You can use this 
+      method to save the final value of the inline editor and to perform any 
+      other cleanup you need to do.
+      
+      @param inlineEditor {SC.InlineTextFieldView} the inline editor
+      @param finalValue {Object} the final value
+      @returns {void}
+    */
+    inlineEditorDidEndEditing: function(inlineEditor, finalValue) {}
+};

data/frameworks/sproutcore/mixins/observable.js

@@ -6,9 +6,11 @@
 /**
   @namespace 
   
-  Key-Value Observing is one of the fundamental ways that models, controllers
-  and views communicate with each other in a SproutCore application.  Any 
-  object that has this module applied to it can be used in KVO-operations.
+  Key-Value-Observing (KVO) simply allows one object to observe changes to a 
+  property on another object. It is one of the fundamental ways that models, 
+  controllers and views communicate with each other in a SproutCore 
+  application.  Any object that has this module applied to it can be used in 
+  KVO-operations.
   
   This module is applied automatically to all objects that inherit from
   SC.Object, which includes most objects bundled with the SproutCore 
@@ -16,21 +18,22 @@
   but you will use the features provided by this module frequently, so it is
   important to understand how to use it.
   
-  h2. About Key Value Observing
+  h2. Enabling Key Value Observing
 
-  Key-Value-Observing (KVO) simply allows one object to observe changes to a 
-  property on another object.  This can replace much of the "glue code" that
-  you often have to write to make parts of your application work together.
+  With KVO, you can write functions that will be called automatically whenever 
+  a property on a particular object changes.  You can use this feature to
+  reduce the amount of "glue code" that you often write to tie the various 
+  parts of your application together.
   
-  Using KVO is easy.  All you have to do is use the KVO methods to get and set
-  properties.  Instead of writing:
+  To use KVO, just use the KVO-aware methods get() and set() to access 
+  properties instead of accessing properties directly.  Instead of writing:
   
   {{{
     var aName = contact.firstName ;
     contact.firstName = 'Charles' ;
   }}}
-  
-  you use:
+
+  use:
 
   {{{
     var aName = contact.get('firstName') ;
@@ -40,8 +43,36 @@
   get() and set() work just like the normal "dot operators" provided by 
   JavaScript but they provide you with much more power, including not only
   observing but computed properties as well.
+
+  h2. Observing Property Changes
+
+  You typically observe property changes simply by adding the observes() 
+  call to the end of your method declarations in classes that you write.  For
+  example:
+  
+  {{{
+    SC.Object.create({
+      valueObserver: function() {
+        // Executes whenever the "Value" property changes
+      }.observes('value')
+    }) ;
+  }}}
+  
+  Although this is the most common way to add an observer, this capability is
+  actually built into the SC.Object class on top of two methods defined in
+  this mixin called addObserver() and removeObserver().  You can use these two
+  methods to add and remove observers yourself if you need to do so at run 
+  time.  
+  
+  To add an observer for a property, just call:
+  
+  {{{
+    object.addObserver('propertyKey', targetObject, targetAction) ;
+  }}}
+  
+  This will call the 'targetAction' method on the targetObject to be called
+  whenever the value of the propertyKey changes.
   
-  INCOMPLETE
 
 */
 SC.Observable = {
@@ -674,9 +705,7 @@ SC.NotificationQueue = {
     this._flushing = false ;
     
     if (this.queue.length > 0) { 
-      this.invokeLater(this._reflush, 1) ;
+      SC.NotificationQueue.flush.invokeLater(SC.NotificationQueue, 1) ;
     }
-  },
-  
-  _reflush: function() { SC.NotificationQueue.flush(); }
+  }
 } ;

data/frameworks/sproutcore/mixins/scrollable.js

@@ -112,7 +112,6 @@ SC.Scrollable = {
     Scrolls the receiver to the specified x,y coordinate
   */
   scrollTo: function(x,y) {
-    console.log('scrollTo(%@,%@)'.fmt(x,y)) ;
     this.set('scrollFrame', { x: 0-x, y: 0-y }) ;  
   },
   

data/frameworks/sproutcore/tests/controllers/controller.rhtml

@@ -135,16 +135,16 @@ Test.context("Chained SC.Controllers", {
       this.root.discardChanges() ;
       this.child.get('hasChanges').shouldEqual(NO) ;
   },
-
+  
   "root.hasChanges should be FALSE after child.commit if root DOES NOT have other changes": function() {
       // edit child only
       this.child.editorDidChange() ;
       this.root.get('hasChanges').shouldEqual(YES) ;
-
+  
       this.child.commitChanges() ;
       this.root.get('hasChanges').shouldEqual(NO) ;
   },  
-
+  
   "root.hasChanges should be TRUE after child.commit if root DOES have other changes": function() {
       // edit child and root
       this.child.editorDidChange() ;
@@ -154,7 +154,7 @@ Test.context("Chained SC.Controllers", {
       this.child.commitChanges() ;
       this.root.get('hasChanges').shouldEqual(YES) ;
   },  
-
+  
   "root.hasChanges should be FALSE after child.discard if root DOES NOT have other changes": function() {
       // edit child only
       this.child.editorDidChange() ;
@@ -173,8 +173,8 @@ Test.context("Chained SC.Controllers", {
       this.child.discardChanges() ;
       this.root.get('hasChanges').shouldEqual(YES) ;
   },
-
-
+  
+  
   "child.hasChanges should be TRUE if another child cannot commit": function() {
     // edit child and child2
     this.child.editorDidChange() ;
@@ -191,7 +191,7 @@ Test.context("Chained SC.Controllers", {
     this.child.get('hasChanges').shouldEqual(YES) ;
     this.root.get('hasChanges').shouldEqual(YES) ;
   },
-
+  
   "child.hasChanges should be TRUE if another child cannot discard": function() {
     // edit child and child2
     this.child.editorDidChange() ;
@@ -208,12 +208,12 @@ Test.context("Chained SC.Controllers", {
     this.child.get('hasChanges').shouldEqual(YES) ;
     this.root.get('hasChanges').shouldEqual(YES) ;
   },
-
+  
   "root.hasChanges should be TRUE if any child fails to commit": function() {
     // NOTE: Commits are not atomic.  IN this case, child2 fails while child1 succeeds.
     // the hasChanges state of child2 and root must both be TRUE in this case, but 
     // child1's state is undefined.  It may have commited or it may not.
-
+  
     this.child.editorDidChange() ;
     this.child2.editorDidChange() ;
     this.child2.isCommitSuccessful = NO ;
@@ -222,12 +222,12 @@ Test.context("Chained SC.Controllers", {
     this.root.get('hasChanges').shouldEqual(YES) ;
     this.child2.get('hasChanges').shouldEqual(YES) ;
   },
-
+  
   "root.hasChanges should be TRUE if any child fails to discard": function() {
     // NOTE: Commits are not atomic.  IN this case, child2 fails while child1 succeeds.
     // the hasChanges state of child2 and root must both be TRUE in this case, but 
     // child1's state is undefined.  It may have commited or it may not.
-
+  
     this.child.editorDidChange() ;
     this.child2.editorDidChange() ;
     this.child2.isDiscardSuccessful = NO ;
@@ -236,7 +236,7 @@ Test.context("Chained SC.Controllers", {
     this.root.get('hasChanges').shouldEqual(YES) ;
     this.child2.get('hasChanges').shouldEqual(YES) ;
   },
-
+  
   "child.commitChangesImmediately should be inherited from the root": function()
   {
     var Klass = SC.Controller.extend({ commitChangesImmediately: NO });

data/frameworks/sproutcore/tests/controllers/object.rhtml

@@ -86,7 +86,7 @@ Test.context("SC.ObjectController", {
       this.c.get('value').shouldEqualEnum([0,1]) ;
       this.c.get('flag').shouldEqualEnum([YES, NO]) ;
       
-      // get('array').shouldEqual: [ [0,0,0], [1,1,1] ];
+      // get('array').shouldEqual() [ [0,0,0], [1,1,1] ];
       var ar = this.c.get('array') ;
       ar.length.shouldEqual(2) ;
       ar[0].shouldEqualEnum([0,0,0]) ;
@@ -244,7 +244,7 @@ Test.context("SC.ObjectController", {
       this.c.get('value').shouldEqualEnum([0,1]) ;
       this.c.get('flag').shouldEqualEnum([YES, NO]) ;
       
-      // get('array').shouldEqual: [ [0,0,0], [1,1,1] ];
+      // get('array').shouldEqual(): [ [0,0,0], [1,1,1] ];
       var ar = this.c.get('array') ;
       ar.length.shouldEqual(2) ;
       ar[0].shouldEqualEnum([0,0,0]) ;

data/frameworks/sproutcore/views/collection/collection.js

@@ -186,11 +186,11 @@ SC.CollectionView = SC.View.extend(
     Trigger the action method on a single click.
   
     Normally, clicking on an item view in a collection will select the content 
-    object and double clicking will trigger the action method on the collection
-    view.  
+    object and double clicking will trigger the action method on the 
+    collection view.  
   
-    If you set this property to true, then clicking on a view will both select it
-    (if isSelected is true) and trigger the action method.  
+    If you set this property to true, then clicking on a view will both select 
+    it (if isSelected is true) and trigger the action method.  
   
     Use this if you are using the collection view as a menu of items.
   
@@ -206,9 +206,9 @@ SC.CollectionView = SC.View.extend(
     passed property key.  The exampleGroupView will be used to display the 
     items in groups.
   
-    If this property is set, you MUST ensure the items in the content array are
-    already sorted by the group key.  Otherwise item view groups might appear more
-    than once.
+    If this property is set, you MUST ensure the items in the content array 
+    are already sorted by the group key.  Otherwise item view groups might 
+    appear more than once.
   
     @type {String}
   */
@@ -217,25 +217,25 @@ SC.CollectionView = SC.View.extend(
   /**
     The view class to use when creating new item views.
   
-    The collection view will automatically create an instance of the view class
-    you set here for each item in its content array.  You should provide your own
-    subclass for this property to display the type of content you want. 
+    The collection view will automatically create an instance of the view 
+    class you set here for each item in its content array.  You should provide 
+    your own subclass for this property to display the type of content you 
+    want. 
   
     For best results, the view you set here should understand the following 
     properties:
   
-    {{{
-      content: The content object from the content array your view should display
-      isEnabled: True if the view should appear enabled
-      isSelected: True if the view should appear selected
-    }}}
+    - *content* The content object from the content array your view should display
+    - *isEnabled* True if the view should appear enabled
+    - *isSelected* True if the view should appear selected
   
-    In general you do not want your child views to actually respond to mouse and
-    keyboard events themselves.  It is better to let the collection view do that.
+    In general you do not want your child views to actually respond to mouse 
+    and keyboard events themselves.  It is better to let the collection view 
+    do that.
 
-    If you do implement your own event handlers such as mouseDown or mouseUp, you
-    should be sure to actually call the same method on the collection view to
-    give it the chance to perform its own selection housekeeping.
+    If you do implement your own event handlers such as mouseDown or mouseUp, 
+    you should be sure to actually call the same method on the collection view 
+    to give it the chance to perform its own selection housekeeping.
   
     @type {SC.View}
   */
@@ -245,21 +245,21 @@ SC.CollectionView = SC.View.extend(
     The view class to use when displaying item views in groups.
   
     If the groupBy property is not null, then the collection view will create
-    an instance of this view class with the item views that belong to the group
-    as child nodes for each distinct group value it encounters.
+    an instance of this view class with the item views that belong to the 
+    group as child nodes for each distinct group value it encounters.
   
     Your groupView should have two outlets:
   
     {{{
-      labelView: The view to display the group label.  The group value will be set 
-      as the content property of this view.
+      labelView: The view to display the group label.  The group value will be 
+      set as the content property of this view.
     
-      itemView: This is the view the item views will be added to as children to 
-      this view.
+      itemView: This is the view the item views will be added to as children 
+      to this view.
     }}}
   
-    If groupBy is null, then this property will not be used.  The default class
-    provided here simply displays the group value in an H1 tag.
+    If groupBy is null, then this property will not be used.  The default 
+    class provided here simply displays the group value in an H1 tag.
   
     @type {SC.View}
   */
@@ -271,20 +271,21 @@ SC.CollectionView = SC.View.extend(
   }),
   
   /**
-    Invoked when the user double clicks on an item (or single clicks of actOnSelect is true)
+    Invoked when the user double clicks on an item (or single clicks of 
+    actOnSelect is true)
 
     Set this to the name of the action you want to send down the
-    responder chain when the user double clicks on an item (or single clicks if 
-    actOnSelect is true).  You can optionally specify a specific target as well 
-    using the target property.
+    responder chain when the user double clicks on an item (or single clicks 
+    if actOnSelect is true).  You can optionally specify a specific target as 
+    well using the target property.
 
     If you do not specify an action, then the collection view will also try to 
     invoke the action named on the target item view.
     
-    Older versions of SproutCore expected the action property to contain an actual
-    function that would be run.  This format is still supported but is deprecated 
-    for future use.  You should generally use the responder chain to handle your
-    action for you.
+    Older versions of SproutCore expected the action property to contain an 
+    actual function that would be run.  This format is still supported but is 
+    deprecated for future use.  You should generally use the responder chain 
+    to handle your action for you.
     
     @type {String}
   */  
@@ -293,10 +294,10 @@ SC.CollectionView = SC.View.extend(
   /**
     Optional target to send the action to when the user double clicks.
     
-    If you set the action property to the name of an action, you can optionally
-    specify the target object you want the action to be sent to.  This can be
-    either an actual object or a property path that will resolve to an object at
-    the time that the action is invoked.  
+    If you set the action property to the name of an action, you can 
+    optionally specify the target object you want the action to be sent to.  
+    This can be either an actual object or a property path that will resolve 
+    to an object at the time that the action is invoked.  
     
     This property is ignored if you use the deprecated approach of making the
     action property a function.
@@ -309,7 +310,8 @@ SC.CollectionView = SC.View.extend(
     Set to true whenever the content changes and remains true until
     the content has been rerendered.  
     
-    You can also set this to true yourself to be notified when it is completed.
+    You can also set this to true yourself to be notified when it is 
+    completed.
   */
   isDirty: false,
   
@@ -355,8 +357,8 @@ SC.CollectionView = SC.View.extend(
     The CollectionView will use this property to support keyboard navigation 
     using the arrow keys.
     
-    If your collection view is simply a vertical list of items then you do not need
-    to edit this property.
+    If your collection view is simply a vertical list of items then you do not 
+    need to edit this property.
   */
   itemsPerRow: 1,
 
@@ -770,13 +772,15 @@ SC.CollectionView = SC.View.extend(
   },
   
   /**
-    Update the selection state for the item views to reflect the selection array.
+    Update the selection state for the item views to reflect the selection 
+    array.
     
-    This will update the isSelected property of all item views so that only those
-    representing content objects found in the selection array are selected.
+    This will update the isSelected property of all item views so that only 
+    those representing content objects found in the selection array are 
+    selected.
     
-    This method is called automatically whenever your content or selection properties
-    changed.  You should not need to call or override it often.
+    This method is called automatically whenever your content or selection 
+    properties changed.  You should not need to call or override it often.
   */
   updateSelectionStates: function() {
     if (!this._itemViews) return ;
@@ -1275,12 +1279,15 @@ SC.CollectionView = SC.View.extend(
   
   /**
     Select one or more items before the current selection, optionally
-    extending the current selection.  Also scrolls the selected item into view.
+    extending the current selection.  Also scrolls the selected item into 
+    view.
     
     Selection does not wrap around.
     
-    @param extend {Boolean} (Optional) If true, the selection will be extended instead of replaced.  Defaults to false.
-    @param numberOfItems {Integer} (Optional) The number of previous to be selected.  Defaults to 1
+    @param extend {Boolean} (Optional) If true, the selection will be extended 
+      instead of replaced.  Defaults to false.
+    @param numberOfItems {Integer} (Optional) The number of previous to be 
+      selected.  Defaults to 1
     @returns {void}
   */
   selectPreviousItem: function(extend, numberOfItems)
@@ -1341,8 +1348,10 @@ SC.CollectionView = SC.View.extend(
 
     Selection does not wrap around.
     
-    @param extend {Boolean} (Optional) If true, the selection will be extended instead of replaced.  Defaults to false.
-    @param numberOfItems {Integer} (Optional) The number of items to be selected.  Defaults to 1.
+    @param extend {Boolean} (Optional) If true, the selection will be extended 
+      instead of replaced.  Defaults to false.
+    @param numberOfItems {Integer} (Optional) The number of items to be 
+      selected.  Defaults to 1.
     @returns {void}
   */
   selectNextItem: function(extend, numberOfItems)
@@ -1398,9 +1407,9 @@ SC.CollectionView = SC.View.extend(
   },
   
   /**
-  * Scroll the rootElement (if needed) to ensure that the item is visible.
-  * @param {SC.Record} record The record to scroll to
-  * @returns {void}
+    Scroll the rootElement (if needed) to ensure that the item is visible.
+    @param {SC.Record} record The record to scroll to
+    @returns {void}
   */
   scrollToContent: function(record) {
     // find the itemView.  if not present, add one.
@@ -1414,9 +1423,9 @@ SC.CollectionView = SC.View.extend(
     if (itemView) this.scrollToItemView(itemView);
   },
   /**
-  * Scroll the rootElement (if needed) to ensure that the item is visible.
-  * @param {SC.View} view The item view to scroll to
-  * @returns {void}
+    Scroll the rootElement (if needed) to ensure that the item is visible.
+    @param {SC.View} view The item view to scroll to
+    @returns {void}
   */
   scrollToItemView: function( view )
   {
@@ -1434,7 +1443,8 @@ SC.CollectionView = SC.View.extend(
     current selection.
     
     @param items {Array} The item or items to select.
-    @param extendSelection {Boolean} If true, extends the selection instead of replacing it.
+    @param extendSelection {Boolean} If true, extends the selection instead of 
+      replacing it.
   */
   selectItems: function(items, extendSelection) {
     var base = (extendSelection) ? this.get('selection') : [] ;
@@ -1537,7 +1547,7 @@ SC.CollectionView = SC.View.extend(
     // Make sure that saved mouseDown state is always reset in case we do
     // not get a paired mouseUp. (Only happens if subclass does not call us 
     // like it should)
-    this._mouseDownAt = this._shouldDeselect = 
+    this._mouseDownAt = this._shouldDeselect =
       this._shouldReselect = this._refreshSelection = false;
 
     var mouseDownView    = this._mouseDownView = this.itemViewForEvent(ev);
@@ -1574,8 +1584,8 @@ SC.CollectionView = SC.View.extend(
       selection = this._findSelectionExtendedByShift(selection, mouseDownContent) ;
       this.selectItems(selection) ;
       
-    // If no modifier key was pressed, then clicking on the selected item should clear
-    // the selection and reselect only the clicked on item.
+    // If no modifier key was pressed, then clicking on the selected item 
+    // should clear the selection and reselect only the clicked on item.
     } else if (!modifierKeyPressed && isSelected) {
       this._shouldReselect = mouseDownContent;
       
@@ -1608,12 +1618,33 @@ SC.CollectionView = SC.View.extend(
       
     } else {
       if (this._shouldDeselect) this.deselectItems(this._shouldDeselect);
-      if (this._shouldReselect) this.selectItems(this._shouldReselect,false) ;
 
-      // this is invoked if the user clicked on a checkbox.  If this is not 
-      // done then the checkbox might not update properly.
-      if (this._refreshSelection) {
+      // begin editing of an item view IF all of the following is true:
+      //   otherwise, just reselect.
+      if (this._shouldReselect) {
+
+        // - contentValueIsEditable is true
+        var canEdit = this.get('contentValueIsEditable') ;
+        
+        // - the user clicked on an item that was already selected
+        // - is the only item selected
+        if (canEdit) {
+          var sel = this.get('selection') ;
+          canEdit = sel && (sel.get('length') === 1) && (sel.objectAt(0) === this._shouldReselect) ;
+        }
+
+        // - the item view responds to contentHitTest() and returns YES.
+        // - the item view responds to beginEditing and returns YES.
+        if (canEdit) {
+          var itemView = this.itemViewForContent(this._shouldReselect) ;
+          canEdit = itemView && (!itemView.contentHitTest || itemView.contentHitTest(ev)) ;
+          canEdit = (canEdit && itemView.beginEditing) ? itemView.beginEditing() : NO ;
+        }
+        
+        // if cannot edit, just reselect
+        if (!canEdit) this.selectItems(this._shouldReselect,false) ;
       }
+
       this._cleanupMouseDown() ;
     }
 
@@ -1713,6 +1744,29 @@ SC.CollectionView = SC.View.extend(
   },
   
 
+  // if content value is editable and we have one item selected, then edit.
+  // otherwise, invoke action.
+  insertNewline: function() {
+    if (this.get('contentValueIsEditable')) {
+      var sel = this.get('selection') ;
+      if (sel && sel.get('length') === 1) {
+        var itemView = this.itemViewForContent(sel.objectAt(0)) ;
+        if (itemView && itemView.beginEditing) {
+          this.scrollToItemView(itemView) ;
+          itemView.beginEditing() ;
+        }
+      }
+      
+    // invoke action!
+    } else {
+      var sel = this.get('selection') ;
+      var itemView = (sel && sel.get('length') === 1) ? this.itemViewForContent(sel.objectAt(0)) : null ;
+      this._action(itemView, null) ;
+    }
+    
+    return YES ; // always handle
+  },
+  
   // ......................................
   // FIRST RESPONDER
   //
@@ -1898,7 +1952,7 @@ SC.CollectionView = SC.View.extend(
     if ((Date.now() - this._mouseDownAt) < 123) return true ;
     
     // OK, they must be serious, start a drag if possible. 
-    if (this.get('canReorderContent')) {
+    if (this.get('canReorderContent') && this._mouseDownEvent != null) {
 
       // First, get the selection to drag.  Drag an array of selected
       // items appearing in this collection, in the order of the