sproutcore 1.4.5 → 1.5.0.pre.3

data/lib/frameworks/sproutcore/frameworks/foundation/mixins/gestureable.js

@@ -0,0 +1,214 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2011 Strobe Inc. and contributors.
+//            Portions ©2008-2010 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+/**
+  You can mix in SC.Gesturable to your views to add some support for recognizing
+  gestures.
+  
+  SproutCore views have built-in touch events. However, sometimes you may want
+  to recognize gestures like tap, pinch, swipe, etc. This becomes tedious if you
+  need to do this often, and moreso if you need to check for multiple possible
+  gestures on the same view.
+  
+  SC.Gesturable allows you to define a collection of gestures (SC.Gesture objects)
+  that your view should recognize. When a gesture is recognized, methods will be
+  called on the view:
+  
+  - [gestureName](gesture, args...): called when the gesture has occurred. This is 
+    useful for event-style gestures, where you aren't interested in when it starts or
+    ends, but just that it has occurred. SC.SwipeGesture triggers this after the
+    swipe has moved a minimum amount—40px by default.
+
+  - [gestureName]Start(gesture, args...): called when the gesture is first recognized. 
+    For instance, a swipe gesture may be recognized after the finger has moved a 
+    minimum distance in a horizontal.
+    
+  - [gestureName]Changed(gesture, args...): called when some property of the gesture 
+    has changed. For instance, this may be called continuously as the user swipes as 
+    the swipe's distance changes.
+  
+  - [gestureName]Cancelled(gesture, args...): called when a gesture, for one reason 
+    or another, is no longer recognized. For instance, a horizontal swipe gesture 
+    could cancel if the user moves too far in a vertical direction.
+  
+  - [gestureName]End(gesture, args...): called when a gesture ends. A swipe would end
+    when the user lifts their finger.
+  
+  Each of these methods is passed the gesture instance, in addition to any arguments
+  the gesture sends for your convenience. The default swipe gesture sends an SC.Touch
+  instance, the swipe direction, and the distance the swipe has moved in that direction.
+  
+  Using SC.Gesturable
+  ------------------------
+  To make your view recognize gestures, mix in Gesturable and add items to the 'gestures'
+  property:
+  
+      SC.View.extend(SC.Gesturable, {
+        gestures: [SC.PinchGesture, 'mySwipeGesture'],
+        
+        // specifying as a string allows you to configure it:
+        mySwipeGesture: SC.SwipeGesture.extend({
+          direction: SC.SWIPE_VERTICAL,
+          startDistance: 3,
+          swipeDistance: 20
+        }),
+        
+        // handle the swipe action
+        swipe: function(touch, direction) {
+          console.error("Swiped! In direction: " + direction);
+        },
+        
+        swipeStart: function(touch, direction, delta) {
+          console.error("Swipe started in direction: " + direction + "; dist: " + delta);
+        },
+        
+        swipeChanged: function(touch, direction, delta) {
+          console.error("Swipe continued in direction: " + direction + "; dist: " + delta);
+        },
+        
+        swipeEnd: function(touch, direction, delta) {
+          console.error("Completed swipe in direction: " + direction + "; dist: " + delta);
+        }
+        
+      })
+  
+*/
+SC.Gesturable = {
+  concatenatedProperties: ["gestures"],
+  gestures: [],
+  
+  /**
+    @private
+    When SC.Gesturable initializes, any gestures on the view must be instantiated.
+  */
+  initMixin: function() {
+    this.createGestures();
+  },
+  
+  /**
+    @private
+    Instantiates the gestures.
+  */
+  createGestures: function() {
+    var gestures = this.get("gestures"), idx, len = gestures.length, g, _g = [];
+
+    // loop through all gestures
+    for (idx = 0; idx < len; idx++) {
+      // get the proper gesture
+      if (SC.typeOf(gestures[idx]) === SC.T_STRING) {
+        g = this.get(gestures[idx]);
+      } else {
+        g = gestures[idx];
+      }
+      
+      // if it was not found, well, that's an error.
+      if (!g) {
+        throw "Could not find gesture named '" + gestures[idx] + "' on view.";
+      }
+      
+      // if it is a class, instantiate (it really ought to be a class...)
+      if (g.isClass) {
+        g = g.create({
+          view: this
+        });
+      }
+      
+      // and set the gesture instance and add it to the array.
+      if (SC.typeOf(gestures[idx]) === SC.T_STRING) this[gestures[idx]] = g;
+      _g.push(g);
+    }
+    
+    this.set("gestures", _g);
+  },
+  
+  /**
+    Handles touch start by handing it to the gesture recognizing code.
+    
+    If you override touchStart, you will need to call gestureTouchStart to
+    give the gesture system control of the touch. You will continue to get
+    events until if and when a gesture decides to take "posession" of a touch—
+    at this point, you will get a [gestureName]Start event.
+    
+    You do not have to call gestureTouchStart immediately; you can call it
+    at any time. This allows you to avoid passing control until _after_ you
+    have determined your own touchStart, touchesDragged, and touchEnd methods
+    are not going to handle it.
+  */
+  touchStart: function(touch) {
+    this.gestureTouchStart(touch);
+  },
+  
+  /**
+    Tells the gesture recognizing code about touches moving.
+    
+    If you override touchesDragged, you will need to call gestureTouchesDragged
+    (at least for any touches you called gestureTouchStart for in touchStart) to 
+    allow the gesture system to update.
+  */
+  touchesDragged: function(evt, touches) {
+    this.gestureTouchesDragged(evt, touches);
+  },
+  
+  /**
+    Tells the gesture recognizing code about a touch ending.
+    
+    If you override touchEnd, you will need to call gestureTouchEnd
+    for any touches you called touchStart for.
+  */
+  touchEnd: function(touch) {
+    this.gestureTouchEnd(touch);
+  },
+  
+  /**
+    Tells the gesture recognizing system about a new touch.
+    
+    This informs all gestures that a new touch, "unassigned" to any gesture,
+    has been located. Later, each gesture has an opportunity to claim the touch.
+    
+    Once they have claimed the touch, further events will go _directly_ to them—
+    this view will cease receiving the touchesDragged and will not receive a touchEnd.
+  */
+  gestureTouchStart: function(touch) {
+    touch.isInteresting = 0;
+    
+    var gestures = this.get("gestures"), idx, len = gestures.length, g;
+    for (idx = 0; idx < len; idx++) {
+      g = gestures[idx];
+      g.unassignedTouchDidStart(touch);
+    }
+  },
+  
+  /**
+    Tells the gesture recognition system that some touches have moved.
+    
+    This informs all gestures that these touches have changed. All such touches
+    are "unassigned" because all "assigned" touches already get sent directly
+    to the gesture.
+  */
+  gestureTouchesDragged: function(evt, touches) {
+    var gestures = this.get("gestures"), idx, len = gestures.length, g;
+    for (idx = 0; idx < len; idx++) {
+      g = gestures[idx];
+      g.unassignedTouchesDidChange(evt, touches);
+    }
+  },
+  
+  /**
+    Tells the gesture recognition system that a touch have ended.
+    
+    This informs all of the gestures that the touch ended. The touch is
+    an unassigned touch as, if it were assigned to a gesture, it would have
+    been sent directly to the gesture, bypassing this view.
+  */
+  gestureTouchEnd: function(touch) {
+    var gestures = this.get("gestures"), idx, len = gestures.length, g;
+    for (idx = 0; idx < len; idx++) {
+      g = gestures[idx];
+      g.unassignedTouchDidEnd(touch);
+    }
+  }
+};

data/lib/frameworks/sproutcore/frameworks/foundation/mixins/inline_editable.js

@@ -0,0 +1,89 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2011 Strobe Inc. and contributors.
+//            Portions ©2008-2010 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+/**
+  This mixin is used for views that show a seperate editor view to edit. If your view is itself editable, use SC.Editable.
+  
+  To use this, you must also implement an InlineEditorDelegate to manage the editor view and an InlineEditableDelegate to manage the result of editing. For simplicity these may all be implemented by your view itself, but for more complex views or editors they should be kept seperate.
+*/
+// TODO: ask juan if this should be combined with SC.Editable
+SC.InlineEditable = {
+  
+  editorDelegate: null,
+  /**
+    Enables editing using the inline editor.
+  */
+  isEditable: YES,
+
+  /**
+    YES if currently editing label view.
+  */
+  isEditing: NO,
+  
+  /**
+    Opens the inline text editor (closing it if it was already open for 
+    another view).
+    
+    @return {Boolean} YES if did begin editing
+  */
+  beginEditing: function() {
+    if(this.get('isEditing')) return YES;
+    
+    return this.invokeDelegateMethod(this.get('editorDelegate'), 'beginEditingFor', this, this.get('value'));
+  },
+  
+  /**
+    Cancels the current inline editor and then exits editor. 
+    
+    @return {Boolean} NO if the editor could not exit.
+  */
+  discardEditing: function() {
+    if (!this.get('isEditing')) return YES;
+    
+    return this.invokeDelegateMethod(this.get('editorDelegate'), 'discardEditingFor', this);
+  },
+  
+  /**
+    Commits current inline editor and then exits editor.
+    
+    @return {Boolean} NO if the editor could not exit
+  */
+  commitEditing: function() {
+    if (!this.get('isEditing')) return YES;
+    
+    return this.invokeDelegateMethod(this.get('editorDelegate'), 'commitEditingFor', this);
+  },
+  
+  /** @private
+    Set editing to true so edits will no longer be allowed.
+  */
+  inlineEditorWillBeginEditing: function(editor) {
+    this.set('isEditing', YES);
+  },
+
+  /** @private 
+    Hide the label view while the inline editor covers it.
+  */
+  inlineEditorDidBeginEditing: function(editor) {
+    return YES;
+  },
+  
+  // TODO: use validator
+  inlineEditorShouldCommitEditing: function(editor, finalValue) {
+    this.setIfChanged('value', finalValue) ;
+    return YES;
+  },
+  
+  /** @private
+    Update the field value and make it visible again.
+  */
+  inlineEditorDidEndEditing: function(editor, finalValue) {
+    this.inlineEditorShouldCommitEditing(editor, finalValue);
+    this.set('isEditing', NO) ;
+    return YES;
+  }
+};

data/lib/frameworks/sproutcore/frameworks/foundation/mixins/inline_editor_delegate.js

@@ -0,0 +1,139 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2011 Strobe Inc. and contributors.
+//            Portions ©2008-2010 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+/**
+  This delegate controls the editing capability of a view. It allows you to customize when a view that uses it is allowed to begin and end editing, as well as the type of editor it uses.
+  
+  By default it edits an SC.LabelView using an SC.InlineTextFieldView.
+  
+  @since SproutCore 1.0
+*/
+SC.InlineEditorDelegate = {
+  // quack
+  isInlineEditorDelegate: YES,
+
+  /**
+    The exampleInlineTextFieldView property is by default a 
+    SC.InlineTextFieldView but it can be set to a customized inline text field
+    view.
+
+    @property
+    @type {SC.View}
+    @default {SC.InlineTextFieldView}
+  */
+  exampleInlineTextFieldView: SC.InlineTextFieldView,
+  
+  inlineEditorClassName: null,
+
+  /**
+    If you want the inline editor to be multiline set this property to YES.
+  
+    @type {Boolean}
+    @default {NO}
+  */
+  isInlineEditorMultiline: NO,
+
+  /**
+    Call to tell the delegate to begin editing the given view. Returns YES if it was able to begin editing.
+  
+    @param {SC.View} the view the user is trying to edit
+    @param {Object} the current value of the view
+    @returns {Boolean} YES if the view began editing
+  */
+  beginEditingFor: function(view, startingValue) {
+    if(!view.get('isEditable')) return NO;
+    if(view.get('isEditing')) return YES;
+    
+    var el = view.$(),
+        value = view.get('value') || '',
+        f = SC.viewportOffset(el[0]),
+        frameTemp = view.convertFrameFromView(view.get('frame'), null),
+        exampleEditor = this.get('exampleInlineTextFieldView');
+        f.width=frameTemp.width;
+        f.height=frameTemp.height;
+    
+    view.inlineEditorWillBeginEditing();
+    
+    exampleEditor.beginEditing({
+      pane: view.get('pane'),
+      frame: f,
+      layout: view.get('layout'),
+      exampleInlineTextFieldView: exampleEditor,
+      delegate: this,
+      inlineEditorClassName: this.get('inlineEditorClassName'),
+      exampleElement: el,
+      value: startingValue,
+      multiline: this.get('isInlineEditorMultiline'),
+      isCollection: NO
+    });
+    
+    exampleEditor.editor._target = view;
+  },
+
+  /**
+    The view the editor view should attach itself to as child. For example if you are editing a row of a formview inside a scrollview, you should attach to the scrollview's containerview or the formview's div, not the label itself. This way you will scroll with the target view but also be above it so editors can reuse views.
+  
+    @param {SC.View} the view attempting to begin editing
+    @returns {SC.View} the view that the editor should be a child of
+  */
+  parentViewForEditor: function(view) {
+    return view.get('parentView');
+  },
+
+  /**
+    Called to tell the editor associated with the given view that the user wants to end editing and save their changes.
+  
+    @param {SC.View} the view whose edit mode is being commited
+    @param {Object} the current value of the view
+    @returns {Boolean} YES if the editor was able to end and commit
+  */
+  commitEditingFor: function(view) {
+    if(!view.get('isEditing')) return NO;
+    
+    // TODO: figure out how a validator works without a form
+    return SC.InlineTextFieldView.commitEditing();
+  },
+  
+  /**
+    Called to tell the editor associated with the given view that the user wants to end editing and discard their changes.
+  
+    @param {SC.View} the view whose edit mode is ending
+    @param {Object} the current value of the view
+    @returns {Boolean} YES if the editor was able to end
+  */
+  discardEditingFor: function(view) {
+    if(!view.get('isEditing')) return NO;
+    
+    return SC.InlineTextFieldView.discardEditing();
+  },
+  
+  /*************
+    Calls from the editor to the view
+    These only have did, not will, because the delegate decides what to do with them.
+  *************/
+  // notify the view that its editor began editing
+  inlineEditorDidBeginEditing: function(editor) {
+    var view = editor._target;
+
+    return view.inlineEditorDidBeginEditing(editor);
+  },
+  
+  // returns true if the finalvalue is valid, false otherwise
+  // this is seperate function from inlineEditorDidCommitEditing because it could just be validiting without actually commiting, for example if a field validates as you type
+  inlineEditorShouldCommitEditing: function(editor, finalValue) {
+    var view = editor._target;
+    
+    return view.inlineEditorShouldCommitEditing(editor, finalValue);
+  },
+  
+  // ask the view if finalvalue is valid, and then commit it and cleanup the editor
+  inlineEditorDidEndEditing: function(editor, finalValue) {
+    var view = editor._target;
+    
+    return view.inlineEditorDidEndEditing(editor, finalValue);
+  }
+};

data/lib/frameworks/sproutcore/frameworks/foundation/mixins/inline_text_field.js

@@ -4,6 +4,7 @@
 // ========================================================================
 
 sc_require('views/text_field') ;
+sc_require('system/utils/misc') ;
 
 /**
   @class
@@ -76,10 +77,9 @@ sc_require('views/text_field') ;
   refuses it as well.
   
   @extends SC.TextFieldView
-  @extends SC.DelegateSupport
   @since SproutCore 1.0
 */
-SC.InlineTextFieldView = SC.TextFieldView.extend(SC.DelegateSupport,
+SC.InlineTextFieldView = SC.TextFieldView.extend(
 /** @scope SC.InlineTextFieldView.prototype */ {
 
   /**
@@ -108,18 +108,11 @@ SC.InlineTextFieldView = SC.TextFieldView.extend(SC.DelegateSupport,
     // can't begin editing again if already editing
     if (this.get('isEditing')) return NO ;
     
-    var layout={}, pane, delLayout, paneElem, del;
+    var layout={}, pane, tarLayout, paneElem, del;
 
-    del = this._delegate = options.delegate ;
-    this.set('delegate', del);
+    del = options.delegate ;
+    this.set('editorDelegate', del) ;
     
-    // continue only if the delegate allows it
-    if (!this.invokeDelegateMethod(del, 'inlineEditorShouldBeginEditing', this)) {
-      //@if(debug)
-      SC.Logger.warn('InlineTextField.beginEditing() cannot begin without inlineEditorShouldBeginEditing() on the delegate.');
-      //@end
-      return NO;
-    }
     this.beginPropertyChanges();
     
     this.set('isEditing', YES) ;
@@ -151,22 +144,22 @@ SC.InlineTextFieldView = SC.TextFieldView.extend(SC.DelegateSupport,
     
     // add to window.
     
-    pane = del.get('pane');
+    pane = options.pane;
 
     layout.height = this._optframe.height;
     layout.width=this._optframe.width;
-    delLayout = this._delegate.get('layout');
+    tarLayout = options.layout;
     paneElem = pane.$()[0];
-    if (this._optIsCollection && delLayout.left) {
-      layout.left=this._optframe.x-delLayout.left-paneElem.offsetLeft-1;
+    if (this._optIsCollection && tarLayout.left) {
+      layout.left=this._optframe.x-tarLayout.left-paneElem.offsetLeft-1;
       if(SC.browser.msie==7) layout.left--;
     } else {
       layout.left=this._optframe.x-paneElem.offsetLeft-1;
       if(SC.browser.msie==7) layout.left--;
     }
     
-    if (this._optIsCollection && delLayout.top) {
-      layout.top=this._optframe.y-delLayout.top-paneElem.offsetTop;
+    if (this._optIsCollection && tarLayout.top) {
+      layout.top=this._optframe.y-tarLayout.top-paneElem.offsetTop;
       if(SC.browser.msie==7) layout.top=layout.top-2;
     } else {
       layout.top=this._optframe.y-paneElem.offsetTop;
@@ -180,12 +173,11 @@ SC.InlineTextFieldView = SC.TextFieldView.extend(SC.DelegateSupport,
    
     pane.appendChild(this);
     
-    this._className = this.getDelegateProperty(del,"inlineEditorClassName");
+    this._className = options.inlineEditorClassName;
     if(this._className && !this.hasClassName(this._className)) {
       this.setClassName(this._className,true);
     }
     
-    this.invokeDelegateMethod(del, 'inlineEditorWillBeginEditing', this) ;
     // this.resizeToFit(this.getFieldValue()) ;
 
     this._previousFirstResponder = pane ? pane.get('firstResponder') : null;
@@ -196,10 +188,10 @@ SC.InlineTextFieldView = SC.TextFieldView.extend(SC.DelegateSupport,
       
     // Become first responder and notify the delegate after run loop completes
     this.invokeLast(function() {
-      this.invokeDelegateMethod(del, 'inlineEditorDidBeginEditing', this);
+      del.inlineEditorDidBeginEditing(this);
     });
     
-    return this;
+    return YES;
   },
   
   
@@ -225,7 +217,7 @@ SC.InlineTextFieldView = SC.TextFieldView.extend(SC.DelegateSupport,
     @returns {Boolean}
   */
   discardEditing: function() {
-    return this._endEditing(this._originalValue, null, YES) ;
+    return this._endEditing(this._originalValue) ;
   },
   
   /**
@@ -236,7 +228,7 @@ SC.InlineTextFieldView = SC.TextFieldView.extend(SC.DelegateSupport,
   */
   blurEditor: function(evt) {
     if (!this.get('isEditing')) return YES ;
-    return this._commitOnBlur ? this.commitEditing(evt) : this.discardEditing(evt);  
+    return this._commitOnBlur ? this.commitEditing(evt) : this.discardEditing(evt);
   },
   
   /** @private
@@ -248,19 +240,20 @@ SC.InlineTextFieldView = SC.TextFieldView.extend(SC.DelegateSupport,
     @returns {Boolean} NO if editing did not exit
   */
   _endEditing: function(finalValue, evt, didDiscard) {
-    if (!this.get('isEditing')) return YES ;
-    
     // get permission from the delegate.
-    var del = this._delegate ;
-    if (!this.invokeDelegateMethod(del, 'inlineEditorShouldEndEditing', this, finalValue, evt, didDiscard)) {
+    var del = this.get('editorDelegate') ;
+    
+    if (!this.get('isEditing') || !del) return YES ;
+    
+    if (!del.inlineEditorShouldCommitEditing(this, finalValue)) {
       //@if(debug)
-      SC.Logger.warn('InlineTextField._endEditing() cannot end without inlineEditorShouldEndEditing() on the delegate.');
+      SC.Logger.warn('InlineTextField._endEditing() cannot end without inlineEditorShouldCommitEditing() on the delegate.');
       //@end
       return NO;
     }
     // OK, we are allowed to end editing.  Notify delegate of final value
     // and clean up.
-    this.invokeDelegateMethod(del, 'inlineEditorDidEndEditing', this, finalValue, evt, didDiscard) ;
+    del.inlineEditorDidEndEditing(this, finalValue);
 
     // If the delegate set a class name, let's clean it up:
     if(this._className) this.setClassName(this._className, false);
@@ -412,7 +405,6 @@ SC.InlineTextFieldView = SC.TextFieldView.extend(SC.DelegateSupport,
         this.set('value', this.$input().val());
       }
       
-      
       this.commitEditing() ;
       return YES ;
     }
@@ -483,7 +475,7 @@ SC.InlineTextFieldView.mixin(
     // the default, this.
     var klass = options.exampleInlineTextFieldView 
               ? options.exampleInlineTextFieldView : this,
-        layout = options.delegate.get('layout'),
+        layout = options.layout,
         s = this.updateViewStyle(),
         p = this.updateViewPaddingStyle();
     
@@ -582,4 +574,4 @@ SC.InlineTextFieldView.mixin(
   */
   editor: null
   
-}) ;
+}) ;