sproutcore 1.6.0.beta.2-x86-mingw32

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-2011 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+/**
+  @namespace
+  
+  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,254 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2011 Strobe Inc. and contributors.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+/**
+  @mixin
+
+  This mixin is used for views that show a seperate editor view to edit.
+  For example, the default behavior of SC.LabelView if isEditable is set
+  to YES is to popup an SC.InlineTextFieldView when double clicked. This is a
+  seperate text input that will handle the editing and save its value back to
+  the label when it is finished.
+
+  To use this functionality, all you have to do is apply this mixin to
+  your view. You may define your own SC.InlineEditorDelegate to further
+  customize editing behavior.
+
+      MyProject.MyView = SC.View.extend(SC.InlineEditable, {
+        inlineEditorDelegate: myDelegate
+      });
+
+  The delegate methods will default to your view unless the
+  inlineEditorDelegate implements them. Simple views do not require a
+  seperate delegate. If your view has a more complicated editing
+  interaction, you may also implement a custom delegate. For example, if
+  you have a form with several views that all edit together, you might
+  set the parent view as the delegate so it can manage the lifecycle and
+  layout of the editors.
+
+  See SC.InlineEditorDelegate for more information on using a delegate to
+  customize your view's edit behavior.
+
+  Your view can now be edited by calling beginEditing() on it.
+
+      myView.beginEditing();
+
+  This will create an editor for the view. You can then end the editing process
+  by calling commitEditing() or discardEditing() on either the view or the
+  editor. commitEditing() will save the value and discard will revert to the
+  original value.
+
+      myView.commitEditing();
+      myView.discardEditing();
+
+  Note that the editor is a private property of the view, so the only views that
+  should be able to access the methods on it are the editor itself, the view it
+  is editing, and their delegates.
+*/
+SC.InlineEditable = {
+
+  /**
+    Walk like a duck.
+
+    @type Boolean
+    @default YES
+  */
+  isInlineEditable: YES,
+
+  /**
+    Flag to enable or disable editing.
+
+    @type Boolean
+    @default YES
+  */
+  isEditable: YES,
+
+  /**
+    The view that will be used to edit this view. Defaults to
+    SC.InlineTextFieldView, which is simply a text field that positions itself
+    over the view being edited.
+
+    @type SC.InlineEditor
+    @default SC.InlineTextFieldView
+  */
+  exampleEditor: SC.InlineTextFieldView,
+
+  /**
+    Indicates whether the view is currently editing. Attempting to
+    beginEditing a view that is already editing will fail.
+
+    @type Boolean
+    @default NO
+  */
+  isEditing: NO,
+
+  /**
+    Delegate that will be notified of events related to the editing
+    process. Also responsible for managing the lifecycle of the editor.
+
+    @type SC.InlineEditorDelegate
+    @default SC.InlineTextFieldDelegate
+  */
+  inlineEditorDelegate: SC.InlineTextFieldDelegate,
+
+  /**
+    @private
+    The editor responsible for editing this view.
+  */
+  _editor: null,
+
+  /**
+    Tells the view to start editing. This will create an editor for it
+    and transfer control to the editor.
+
+    Will fail if the delegate returns NO to inlineEditorShouldBeginEditing.
+
+    @returns {Boolean} whether the view succesfully entered edit mode
+  */
+  beginEditing: function() {
+    var del;
+
+    del = this.delegateFor('inlineEditorShouldBeginEditing', this.inlineEditorDelegate);
+    if(del && !del.inlineEditorShouldBeginEditing(this, this.get('value'))) return NO;
+
+    this._editor = this.invokeDelegateMethod(this.inlineEditorDelegate, 'acquireEditor', this);
+
+    if(this._editor) return this._editor.beginEditing(this);
+    else return NO;
+  },
+
+  /**
+    Tells the view to save the value currently in the editor and finish
+    editing. The delegate will be consulted first by calling
+    inlineEditorShouldCommitEditing, and the operation will not be
+    allowed if the delegate returns NO.
+
+    Will fail if the delegate returns NO to inlineEditorShouldCommitEditing.
+
+    @returns {Boolean} whether the delegate allowed the value to be committed
+  */
+  commitEditing: function() {
+    return this._editor ? this._editor.commitEditing() : NO;
+  },
+
+  /**
+    Tells the view to leave edit mode and revert to the value it had
+    before editing. May fail if the delegate returns NO to
+    inlineEditorShouldDiscardEditing. It is possible for the delegate to
+    return false to inlineEditorShouldDiscardEditing but true to
+    inlineEditorShouldCommitEditing, so a client view may attempt to
+    call commitEditing in case discardEditing fails.
+
+    Will fail if the delegate returns NO to inlineEditorShouldDiscardEditing.
+
+    @returns {Boolean} whether the delegate allowed the view to discard its value
+  */
+  discardEditing: function() {
+    return this._editor ? this._editor.discardEditing() : NO;
+  },
+
+  /**
+    Allows the view to begin editing if it is editable and it is not
+    already editing.
+
+    @returns {Boolean} if the view is allowed to begin editing
+  */
+  inlineEditorShouldBeginEditing: function() {
+    return !this.isEditing && this.isEditable;
+  },
+
+  // TODO: implement validator
+  /**
+    By default, the editor starts with the value of the view being edited.
+
+    @params {SC.InlineEditable} editor the view being edited
+    @params {SC.InlineEditor} value the editor for the view
+    @params {Object} editable the initial value of the editor
+  */
+  inlineEditorWillBeginEditing: function(editor, value, editable) {
+    editor.set('value', this.get('value'));
+  },
+
+  /**
+    Sets isEditing to YES once editing has begun.
+
+    @params {SC.InlineEditable} the view being edited
+    @params {SC.InlineEditor} the editor for the view
+    @params {Object} the initial value of the editor
+  */
+  inlineEditorDidBeginEditing: function(editor, value, editable) {
+    this.set('isEditing', YES);
+  },
+
+  /** @private
+    Calls inlineEditorWillEndEditing for backwards compatibility.
+
+    @params {SC.InlineEditable} the view being edited
+    @params {SC.InlineEditor} the editor for the view
+    @params {Object} the initial value of the editor
+  */
+  inlineEditorWillCommmitEditing: function(editor, value, editable) {
+    if(this.inlineEditorWillEndEditing) this.inlineEditorWillEndEditing(editor, value);
+  },
+
+  /**
+    By default, commiting editing simply sets the value that the editor
+    returned and cleans up.
+
+    @params {SC.InlineEditable} the view being edited
+    @params {SC.InlineEditor} the editor for the view
+    @params {Object} the initial value of the editor
+  */
+  inlineEditorDidCommitEditing: function(editor, value, editable) {
+    editable.setIfChanged('value', value);
+
+    if(this.inlineEditorDidEndEditing) this.inlineEditorDidEndEditing(editor, value);
+
+    this._endEditing();
+  },
+
+  /**
+    Calls inlineEditorWillEndEditing for backwards compatibility.
+
+    @params {SC.InlineEditable} the view being edited
+    @params {SC.InlineEditor} the editor for the view
+    @params {Object} the initial value of the editor
+  */
+  inlineEditorWillDiscardEditing: function(editor, editable) {
+    if(this.inlineEditorWillEndEditing) this.inlineEditorWillEndEditing(editor, this.get('value'));
+  },
+
+  /**
+    Calls inlineEditorDidEndEditing for backwards compatibility and then
+    cleans up.
+
+    @params {SC.InlineEditable} the view being edited
+    @params {SC.InlineEditor} the editor for the view
+    @params {Object} the initial value of the editor
+  */
+  inlineEditorDidDiscardEditing: function(editor, editable) {
+    if(this.inlineEditorDidEndEditing) this.inlineEditorDidEndEditing(editor, this.get('value'));
+
+    this._endEditing();
+  },
+
+  /**
+    @private
+    Shared code used to cleanup editing after both discarding and commiting.
+  */
+  _endEditing: function() {
+    // _editor may be null if we were called using the
+    // SC.InlineTextFieldView class methods
+    if(this._editor) {
+      this.invokeDelegateMethod(this.inlineEditorDelegate, 'releaseEditor', this._editor);
+      this._editor = null;
+    }
+
+    this.set('isEditing', NO);
+  }
+};
+

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

@@ -0,0 +1,188 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2010 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+/**
+  @mixin
+
+  This mixin is for a view that is editable but is acting as a proxy to
+  edit another view. For example, a calendar picker that pops up over
+  top of a date display.
+
+  Instantiation and destruction will be handled by the InlineEditorDelegate
+  defined on the InlineEditable view.
+
+  Any runtime configuration should be handled by the delegate's
+  inlineEditorWillBeginEditing method. This will be done at the start of the
+  beginEditing function, so your view should be able to handle having value
+  changed by this method.
+
+  Your view should also be sure to cleanup completely when editing is finished,
+  because the delegate may decide to reuse the same editor elsewhere.
+
+  See SC.InlineTextFieldView for an example of an implementation of
+  SC.InlineEditor.
+*/
+SC.InlineEditor = {
+
+  /**
+    Walk like a duck.
+
+    @type Boolean
+    @default YES
+    @readOnly
+  */
+  isInlineEditor: YES,
+
+  /**
+    Indicates the view is currently editing. For a typical editor, this
+    will always be true as long as the view exists, but some
+    InlineEditorDelegates may have more complex lifecycles in which
+    editors are reused.
+
+    @type Boolean
+    @default NO
+  */
+  isEditing: NO,
+
+  /**
+    The delegate responsible for the editors lifecycle as well as the
+    target for notifications. This property should be set when the
+    delegate creates the editor and does not need to be in the view
+    definition.
+
+    @type SC.InlineEditorDelegate
+    @default null
+  */
+  inlineEditorDelegate: null,
+
+  /**
+    @private
+    The view that this view is responsible for editing.
+    @type SC.InlineEditable
+  */
+  _target: null,
+
+  /**
+    Tells the editor to begin editing another view with the given starting value.
+    Editors may be reused so make sure that the editor is fully cleaned
+    up and reinitialized.
+
+    Sets isEditing to YES.
+
+    Will fail if the editor is already editing.
+
+    If you override this method, be sure to call sc_super() at the beginning of
+    you function so that the delegate will be able to configure the view when it
+    is notified of the inlineEditorWillBeginEditing event.
+
+    @param {SC.View} editable the view being edited
+    @returns {Boolean} whether the editor was able to successfully begin editing
+  */
+  beginEditing:function(editable) {
+    if(this.get('isEditing') || !editable) return NO;
+
+    var del, target;
+
+    target = this._target = editable;
+
+    del = this.delegateFor('inlineEditorWillBeginEditing', this.inlineEditorDelegate, target);
+    if(del) del.inlineEditorWillBeginEditing(this, this.get('value'), target);
+
+    this.set('isEditing', YES);
+
+    // needs to be invoked last because it needs to run after the view becomes
+    // first responder
+    this.invokeLast(this._callDidBegin);
+
+    return YES;
+  },
+
+  /**
+    @private
+    Notifies the delegate of the didBeginEditing event. Needs to be invoked last
+    because becoming first responder doesn't happen until the end of the runLoop
+    and didBegin is supposed to occur after the editor becomes first responder.
+  */
+  _callDidBegin: function() {
+    var target = this._target, del;
+
+    del = this.delegateFor('inlineEditorDidBeginEditing', this.inlineEditorDelegate, target);
+    if(del) del.inlineEditorDidBeginEditing(this, this.get('value'), target);
+  },
+
+  /**
+    Tells the editor to save its value back to its target view and end
+    editing. Since the editor is a private property of the view it is
+    editing for, this function should only be called from the editor
+    itself. For example, you may want your editor to handle the enter
+    key by calling commitEditing on itself.
+
+    Will fail if the editor is not editing or if the delegate returns NO to
+    inlineEditorShouldCommitEditing.
+
+    @returns {Boolean} whether the editor was allowed to successfully commit its value
+  */
+  commitEditing:function() {
+    if(!this.get('isEditing')) return NO;
+
+    var del, target = this._target;
+
+    del = this.delegateFor('inlineEditorShouldCommitEditing', this.inlineEditorDelegate, target);
+    if(del && !del.inlineEditorShouldCommitEditing(this, this.get('value'), target)) return NO;
+
+    del = this.delegateFor('inlineEditorWillCommitEditing', this.inlineEditorDelegate, target);
+    if(del) del.inlineEditorWillCommitEditing(this, this.get('value'), target);
+
+    this._endEditing();
+
+    del = this.delegateFor('inlineEditorDidCommitEditing', this.inlineEditorDelegate, target);
+    if(del) del.inlineEditorDidCommitEditing(this, this.get('value'), target);
+
+    return YES;
+  },
+
+  /**
+    Tells the editor to discard its value and end editing. Like
+    commitEditing, this should only be called by other methods of the
+    editor. For example, the handle for the escape key might call
+    discardEditing.
+
+    Will fail if the editor is not editing or if the delegate returns NO to
+    inlineEditorShouldDiscardEditing.
+
+    @returns {Boolean} whether the editor was allowed to discard its value
+  */
+  discardEditing:function() {
+    if(!this.get('isEditing')) return NO;
+
+    var del, target = this._target;
+
+    del = this.delegateFor('inlineEditorShouldDiscardEditing', this.inlineEditorDelegate, target);
+    if(del && !del.inlineEditorShouldDiscardEditing(this, target)) return NO;
+
+    del = this.delegateFor('inlineEditorWillDiscardEditing', this.inlineEditorDelegate, target);
+    if(del) del.inlineEditorWillDiscardEditing(this, target);
+
+    this._endEditing();
+
+    del = this.delegateFor('inlineEditorDidDiscardEditing', this.inlineEditorDelegate, target);
+    if(del) del.inlineEditorDidDiscardEditing(this, target);
+
+    return YES;
+  },
+
+  /**
+    @private
+    Performs the cleanup functionality shared between discardEditing and
+    commitEditing.
+  */
+  _endEditing: function() {
+    this.set('isEditing', NO);
+    this._target = null;
+  }
+
+};