1 // ==========================================================================
  2 // Project:   SproutCore - JavaScript Application Framework
  3 // Copyright: ©2006-2011 Strobe Inc. and contributors.
  4 //            Portions ©2008-2011 Apple Inc. All rights reserved.
  5 // License:   Licensed under MIT license (see license.js)
  6 // ==========================================================================
  7 
  8 /**
  9   @namespace
 10   
 11   This delegate is consulted by view implementing SC.InlineEditable and
 12   SC.InlineEditor and controls the lifecycle of the editor as well as begin
 13   notified of events in the editing process.
 14   
 15   By default it edits an SC.LabelView using an SC.InlineTextFieldView.
 16 
 17   All methods will be attempted to be called on the inlineEditorDelegate of the
 18   inlineEditor or inlineEditable first and then the target view if it didn't exist
 19   on the delegate. This allows you to implement default delegate handlers on your
 20   editable view.
 21   
 22   @since SproutCore 1.0
 23 */
 24 SC.InlineEditorDelegate = {
 25 
 26   // ..........................................................
 27   // Required Functions
 28   // 
 29 
 30   /**
 31     Acquires an editor for the view. This may simply create one and return it,
 32     or you may implement more complex lifecycle management like pooling of
 33     editors.
 34 
 35     May return null if for some reason an editor could not be required.
 36 
 37     You must override this function.
 38 
 39     @params {SC.InlineEditable} editable the view that is begin edited
 40     @returns {SC.InlineEditor} an editor for the view
 41   */
 42   acquireEditor:function(editable) {},
 43 
 44   /**
 45     Releases an editor. This may simply remove it from its parent and dispose of
 46     it, or you may implement more complex lifecycle management like pooling of
 47     editors.
 48 
 49     You must override this function.
 50 
 51     @params {SC.InlineEditor} editor the editor being released
 52     @returns {Boolean} YES if it was successfully released
 53   */
 54   releaseEditor:function(editor) {},
 55 
 56 
 57   // ..........................................................
 58   // Optional Functions
 59   // 
 60 
 61   /**
 62     Determines if the view should be allowed to begin editing and returns YES if
 63     so. Isn't passed the editor because it hasn't been created yet. If this
 64     method is not defined the editor will assume it is always allowed to begin
 65     editing.
 66 
 67     @params {SC.InlineEditable} editable the view that is attempting to begin editing
 68     @params {Object} value the current value of the view
 69     @returns {Boolean} YES if the view is allowed to edit
 70   */
 71   inlineEditorShouldBeginEditing: function(editable, value) {},
 72 
 73   /**
 74     Notifies the delegate that the view was allowed to begin editing and the
 75     editor has been acquired, but hasn't actually done any setup. Most views will
 76     set their current value as the starting value of the editor here, and
 77     depending on the editor other configuration options may be available.
 78 
 79     Since the editor's value hasn't been configured with, the value passed here will be
 80     the default value of the editor.
 81 
 82     @params {SC.InlineEditable} the view being edited
 83     @params {SC.InlineEditor} the editor for the view
 84     @params {Object} the value the editor will start with
 85   */
 86   inlineEditorWillBeginEditing:function(editor, value, editable) {},
 87 
 88   /**
 89     Notifies the delegate that the editor has finished setting up itself and is
 90     now editing.
 91 
 92     @params {SC.InlineEditable} the view being edited
 93     @params {SC.InlineEditor} the editor for the view
 94     @params {Object} the value the editor started with
 95   */
 96   inlineEditorDidBeginEditing:function(editor, value, editable) {},
 97 
 98   /**
 99     Determines if the editor is allowed to end editing and store its value back
100     to the view being edited. If this method is not defined the editor will
101     assume it is always allowed to commit.
102 
103     @params {SC.InlineEditable} the view being edited
104     @params {SC.InlineEditor} the editor for the view
105     @params {Object} the value the editor is attempting to commit
106   */
107   inlineEditorShouldCommitEditing:function(editor, value, editable) {},
108 
109   /**
110     Notifies the delegate that the editor was allowed to commit and is going to
111     commit but hasn't actually performed any cleanup yet.
112 
113     @params {SC.InlineEditable} the view being edited
114     @params {SC.InlineEditor} the editor for the view
115     @params {Object} the value the editor ended with
116   */
117   inlineEditorWillCommitEditing:function(editor, value, editable) {},
118 
119   /**
120     Notifies the delegate that the editor was allowed to commit and finished
121     performing any cleanup necessary. This is where you should save the final
122     value back to your view after performing any necessary transforms to it.
123 
124     @params {SC.InlineEditable} the view being edited
125     @params {SC.InlineEditor} the editor for the view
126     @params {Object} the value the editor ended with
127   */
128   inlineEditorDidCommitEditing:function(editor, value, editable) {},
129 
130   /**
131     Determines if the editor is allowed to discard its current value and end
132     editing. If this method is undefined the editor will assume it is always
133     allowed to discard.
134 
135     @params {SC.InlineEditable} the view being edited
136     @params {SC.InlineEditor} the editor for the view
137   */
138   inlineEditorShouldDiscardEditing:function(editor, editable) {},
139 
140   /**
141     Notifies the delegate that the view was allowed to discard editing but
142     hasn't performed any cleanup yet.
143 
144     @params {SC.InlineEditable} the view being edited
145     @params {SC.InlineEditor} the editor for the view
146   */
147   inlineEditorWillDiscardEditing:function(editor, editable) {},
148 
149   /**
150     Notifies the delegate that the editor has finished cleaning up after
151     discarding editing.
152 
153     @params {SC.InlineEditable} the view being edited
154     @params {SC.InlineEditor} the editor for the view
155   */
156   inlineEditorDidDiscardEditing:function(editor, editable) {},
157 
158 
159   // ..........................................................
160   // Backwards Compatibility
161   // 
162 
163   /**
164     @private
165 
166     Notifies the delegate that the editor will end editing but hasn't cleaned up
167     yet. This can be caused by both commit or discard. If it was a discard, the
168     value will be the same as the current value of the editable view. Otherwise,
169     it was a commit and the value will be the value of the editor.
170 
171     This method is for backwards compatibility and should not be used.
172 
173     @params {SC.InlineEditable} the view being edited
174     @params {SC.InlineEditor} the editor for the view
175     @params {Object} the final value of the edit
176   */
177   inlineEditorWillEndEditing: function(editor, value, editable) {},
178 
179   /**
180     @private
181 
182     Notifies the delegate that the editor has cleaned up after editing. This can
183     be caused by both commit or discard. If it was a discard, the value will be
184     the same as the current value of the editable view. Otherwise, it was a
185     commit and the value will be the value of the editor.
186 
187     This method is for backwards compatibility and should not be used.
188 
189     @params {SC.InlineEditable} the view being edited
190     @params {SC.InlineEditor} the editor for the view
191     @params {Object} the final value of the edit
192   */
193   inlineEditorDidEndEditing: function(editor, value, editable) {}
194 };
195 
196