sproutcore 1.5.0.rc.2 → 1.5.0

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

@@ -5,81 +5,82 @@
 // 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.
+/**
+  @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}
+
+  /**
+    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}
+  /**
+    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}
+  /**
+    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}
+  /**
+    @private
+    The view that this view is responsible for editing.
+    @type SC.InlineEditable
   */
   _target: null,
 
-  /*
-  * @method
-  *
-  * 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} the view being edited
-  * @returns {Boolean} whether the editor was able to successfully begin editing
+  /**
+    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;
@@ -100,34 +101,30 @@ SC.InlineEditor = {
     return YES;
   },
 
-  /*
-  * @method
-  * @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.
+  /**
+    @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;
+    var target = this._target, del;
 
     del = this.delegateFor('inlineEditorDidBeginEditing', this.inlineEditorDelegate, target);
     if(del) del.inlineEditorDidBeginEditing(this, this.get('value'), target);
   },
 
-  /*
-  * @method
-  *
-  * 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
+  /**
+    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;
@@ -148,18 +145,16 @@ SC.InlineEditor = {
     return YES;
   },
 
-  /*
-  * #method
-  *
-  * 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
+  /**
+    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;
@@ -180,18 +175,14 @@ SC.InlineEditor = {
     return YES;
   },
 
-  /*
-  * @method
-  * @private
-  *
-  * Performs the cleanup functionality shared between discardEditing and
-  * commitEditing.
+  /**
+    @private
+    Performs the cleanup functionality shared between discardEditing and
+    commitEditing.
   */
   _endEditing: function() {
     this.set('isEditing', NO);
-
     this._target = null;
-
   }
-};
 
+};

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

@@ -6,7 +6,7 @@
 // ==========================================================================
 
 /**
-  @protocol
+  @mixin
   
   This delegate is consulted by view implementing SC.InlineEditable and
   SC.InlineEditor and controls the lifecycle of the editor as well as begin
@@ -22,180 +22,173 @@
   @since SproutCore 1.0
 */
 SC.InlineEditorDelegate = {
-  /** REQUIRED FUNCTIONS **/
-  /*
-  * @method
-  *
-  * Acquires an editor for the view. This may simply create one and return it,
-  * or you may implement more complex lifecycle management like pooling of
-  * editors.
-  *
-  * May return null if for some reason an editor could not be required.
-  *
-  * @params {SC.InlineEditable} the view that is begin edited
-  * @returns {SC.InlineEditor} an editor for the view
+
+  // ..........................................................
+  // Required Functions
+  // 
+
+  /**
+    Acquires an editor for the view. This may simply create one and return it,
+    or you may implement more complex lifecycle management like pooling of
+    editors.
+
+    May return null if for some reason an editor could not be required.
+
+    You must override this function.
+
+    @params {SC.InlineEditable} editable the view that is begin edited
+    @returns {SC.InlineEditor} an editor for the view
   */
   acquireEditor:function(editable) {},
 
-  /*
-  * @method
-  *
-  * Releases an editor. This may simply remove it from its parent and dispose of
-  * it, or you may implement more complex lifecycle management like pooling of
-  * editors.
-  *
-  * @params {SC.InlineEditor} the editor being released
-  * @returns {Boolean} YES if it was successfully released
+  /**
+    Releases an editor. This may simply remove it from its parent and dispose of
+    it, or you may implement more complex lifecycle management like pooling of
+    editors.
+
+    You must override this function.
+
+    @params {SC.InlineEditor} editor the editor being released
+    @returns {Boolean} YES if it was successfully released
   */
   releaseEditor:function(editor) {},
 
-  /** OPTIONAL FUNCTIONS **/
-  /*
-  * @method
-  *
-  * Determines if the view should be allowed to begin editing and returns YES if
-  * so. Isn't passed the editor because it hasn't been created yet. If this
-  * method is not defined the editor will assume it is always allowed to begin
-  * editing.
-  *
-  * @params {SC.InlineEditable} the view that is attempting to begin editing
-  * @params {Object} the current value of the view
-  * @returns {Boolean} YES if the view is allowed to edit
+
+  // ..........................................................
+  // Optional Functions
+  // 
+
+  /**
+    Determines if the view should be allowed to begin editing and returns YES if
+    so. Isn't passed the editor because it hasn't been created yet. If this
+    method is not defined the editor will assume it is always allowed to begin
+    editing.
+
+    @params {SC.InlineEditable} editable the view that is attempting to begin editing
+    @params {Object} value the current value of the view
+    @returns {Boolean} YES if the view is allowed to edit
   */
   inlineEditorShouldBeginEditing: function(editable, value) {},
 
-  /*
-  * @method
-  *
-  * Notifies the delegate that the view was allowed to begin editing and the
-  * editor has been acquired, but hasn't actually done any setup. Most views will
-  * set their current value as the starting value of the editor here, and
-  * depending on the editor other configuration options may be available.
-  *
-  * Since the editor's value hasn't been configured with, the value passed here will be
-  * the default value of the editor.
-  *
-  * @params {SC.InlineEditable} the view being edited
-  * @params {SC.InlineEditor} the editor for the view
-  * @params {Object} the value the editor will start with
+  /**
+    Notifies the delegate that the view was allowed to begin editing and the
+    editor has been acquired, but hasn't actually done any setup. Most views will
+    set their current value as the starting value of the editor here, and
+    depending on the editor other configuration options may be available.
+
+    Since the editor's value hasn't been configured with, the value passed here will be
+    the default value of the editor.
+
+    @params {SC.InlineEditable} the view being edited
+    @params {SC.InlineEditor} the editor for the view
+    @params {Object} the value the editor will start with
   */
   inlineEditorWillBeginEditing:function(editor, value, editable) {},
 
-  /*
-  * @method
-  *
-  * Notifies the delegate that the editor has finished setting up itself and is
-  * now editing.
-  *
-  * @params {SC.InlineEditable} the view being edited
-  * @params {SC.InlineEditor} the editor for the view
-  * @params {Object} the value the editor started with
+  /**
+    Notifies the delegate that the editor has finished setting up itself and is
+    now editing.
+
+    @params {SC.InlineEditable} the view being edited
+    @params {SC.InlineEditor} the editor for the view
+    @params {Object} the value the editor started with
   */
   inlineEditorDidBeginEditing:function(editor, value, editable) {},
 
-  /*
-  * @method
-  *
-  * Determines if the editor is allowed to end editing and store its value back
-  * to the view being edited. If this method is not defined the editor will
-  * assume it is always allowed to commit.
-  *
-  * @params {SC.InlineEditable} the view being edited
-  * @params {SC.InlineEditor} the editor for the view
-  * @params {Object} the value the editor is attempting to commit
+  /**
+    Determines if the editor is allowed to end editing and store its value back
+    to the view being edited. If this method is not defined the editor will
+    assume it is always allowed to commit.
+
+    @params {SC.InlineEditable} the view being edited
+    @params {SC.InlineEditor} the editor for the view
+    @params {Object} the value the editor is attempting to commit
   */
   inlineEditorShouldCommitEditing:function(editor, value, editable) {},
 
-  /*
-  * @method
-  *
-  * Notifies the delegate that the editor was allowed to commit and is going to
-  * commit but hasn't actually performed any cleanup yet.
-  *
-  * @params {SC.InlineEditable} the view being edited
-  * @params {SC.InlineEditor} the editor for the view
-  * @params {Object} the value the editor ended with
+  /**
+    Notifies the delegate that the editor was allowed to commit and is going to
+    commit but hasn't actually performed any cleanup yet.
+
+    @params {SC.InlineEditable} the view being edited
+    @params {SC.InlineEditor} the editor for the view
+    @params {Object} the value the editor ended with
   */
   inlineEditorWillCommitEditing:function(editor, value, editable) {},
 
-  /*
-  * @method
-  *
-  * Notifies the delegate that the editor was allowed to commit and finished
-  * performing any cleanup necessary. This is where you should save the final
-  * value back to your view after performing any necessary transforms to it.
-  *
-  * @params {SC.InlineEditable} the view being edited
-  * @params {SC.InlineEditor} the editor for the view
-  * @params {Object} the value the editor ended with
+  /**
+    Notifies the delegate that the editor was allowed to commit and finished
+    performing any cleanup necessary. This is where you should save the final
+    value back to your view after performing any necessary transforms to it.
+
+    @params {SC.InlineEditable} the view being edited
+    @params {SC.InlineEditor} the editor for the view
+    @params {Object} the value the editor ended with
   */
   inlineEditorDidCommitEditing:function(editor, value, editable) {},
 
-  /*
-  * @method
-  *
-  * Determines if the editor is allowed to discard its current value and end
-  * editing. If this method is undefined the editor will assume it is always
-  * allowed to discard.
-  *
-  * @params {SC.InlineEditable} the view being edited
-  * @params {SC.InlineEditor} the editor for the view
+  /**
+    Determines if the editor is allowed to discard its current value and end
+    editing. If this method is undefined the editor will assume it is always
+    allowed to discard.
+
+    @params {SC.InlineEditable} the view being edited
+    @params {SC.InlineEditor} the editor for the view
   */
   inlineEditorShouldDiscardEditing:function(editor, editable) {},
 
-  /*
-  * @method
-  *
-  * Notifies the delegate that the view was allowed to discard editing but
-  * hasn't performed any cleanup yet.
-  *
-  * @params {SC.InlineEditable} the view being edited
-  * @params {SC.InlineEditor} the editor for the view
+  /**
+    Notifies the delegate that the view was allowed to discard editing but
+    hasn't performed any cleanup yet.
+
+    @params {SC.InlineEditable} the view being edited
+    @params {SC.InlineEditor} the editor for the view
   */
   inlineEditorWillDiscardEditing:function(editor, editable) {},
 
-  /*
-  * @method
-  *
-  * Notifies the delegate that the editor has finished cleaning up after
-  * discarding editing.
-  *
-  * @params {SC.InlineEditable} the view being edited
-  * @params {SC.InlineEditor} the editor for the view
+  /**
+    Notifies the delegate that the editor has finished cleaning up after
+    discarding editing.
+
+    @params {SC.InlineEditable} the view being edited
+    @params {SC.InlineEditor} the editor for the view
   */
   inlineEditorDidDiscardEditing:function(editor, editable) {},
 
-  /** BACKWARDS COMPATIBILITY **/
-  /*
-  * @method
-  *
-  * Notifies the delegate that the editor will end editing but hasn't cleaned up
-  * yet. This can be caused by both commit or discard. If it was a discard, the
-  * value will be the same as the current value of the editable view. Otherwise,
-  * it was a commit and the value will be the value of the editor.
-  *
-  * This method is for backwards compatibility and should not be used.
-  *
-  * @params {SC.InlineEditable} the view being edited
-  * @params {SC.InlineEditor} the editor for the view
-  * @params {Object} the final value of the edit
+
+  // ..........................................................
+  // Backwards Compatibility
+  // 
+
+  /**
+    @private
+
+    Notifies the delegate that the editor will end editing but hasn't cleaned up
+    yet. This can be caused by both commit or discard. If it was a discard, the
+    value will be the same as the current value of the editable view. Otherwise,
+    it was a commit and the value will be the value of the editor.
+
+    This method is for backwards compatibility and should not be used.
+
+    @params {SC.InlineEditable} the view being edited
+    @params {SC.InlineEditor} the editor for the view
+    @params {Object} the final value of the edit
   */
   inlineEditorWillEndEditing: function(editor, value, editable) {},
 
-  /*
-  * @method
-  *
-  * Notifies the delegate that the editor has cleaned up after editing. This can
-  * be caused by both commit or discard. If it was a discard, the value will be
-  * the same as the current value of the editable view. Otherwise, it was a
-  * commit and the value will be the value of the editor.
-
-  *
-  * This method is for backwards compatibility and should not be used.
-  *
-  * @params {SC.InlineEditable} the view being edited
-  * @params {SC.InlineEditor} the editor for the view
-  * @params {Object} the final value of the edit
+  /**
+    @private
+
+    Notifies the delegate that the editor has cleaned up after editing. This can
+    be caused by both commit or discard. If it was a discard, the value will be
+    the same as the current value of the editable view. Otherwise, it was a
+    commit and the value will be the value of the editor.
+
+    This method is for backwards compatibility and should not be used.
+
+    @params {SC.InlineEditable} the view being edited
+    @params {SC.InlineEditor} the editor for the view
+    @params {Object} the final value of the edit
   */
   inlineEditorDidEndEditing: function(editor, value, editable) {}
 };