// ==========================================================================
// 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
  
  This delegate is consulted by view implementing SC.InlineEditable and
  SC.InlineEditor and controls the lifecycle of the editor as well as begin
  notified of events in the editing process.
  
  By default it edits an SC.LabelView using an SC.InlineTextFieldView.

  All methods will be attempted to be called on the inlineEditorDelegate of the
  inlineEditor or inlineEditable first and then the target view if it didn't exist
  on the delegate. This allows you to implement default delegate handlers on your
  editable view.
  
  @since SproutCore 1.0
*/
SC.InlineEditorDelegate = {

  // ..........................................................
  // 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) {},

  /**
    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
  // 

  /**
    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) {},

  /**
    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) {},

  /**
    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) {},

  /**
    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) {},

  /**
    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) {},

  /**
    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) {},

  /**
    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) {},

  /**
    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) {},

  /**
    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
  // 

  /**
    @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) {},

  /**
    @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) {}
};