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