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 /** @namespace 9 The `SC.ResponderProtocol` protocol defines the properties and methods that you may implement 10 in your `SC.Responder` (i.e. `SC.View`) subclasses in order to handle specific responder chain 11 events. 12 13 *Note: Do not mix `SC.ResponderProtocol` into your classes. As a protocol, it exists only for 14 reference sake. You only need define any of the properties or methods listed below in order to use 15 this protocol.* 16 17 @since SproutCore 1.0 18 */ 19 SC.ResponderProtocol = { 20 21 // ....................................................................... 22 // Mouse Event Handlers 23 // 24 25 /** 26 Called when the mouse is pressed. You must return `YES` to receive 27 mouseDragged and mouseUp in the future. 28 29 @param evt {SC.Event} the mousedown event 30 @returns {Boolean} YES to receive additional mouse events, NO otherwise 31 */ 32 mouseDown: function(evt) {}, 33 34 /** 35 Called when the mouse is released. 36 37 @param evt {SC.Event} the mouseup event 38 @returns {Boolean} YES to handle the mouseUp, NO to allow click() and doubleClick() to be called 39 */ 40 mouseUp: function(evt) {}, 41 42 /** 43 Called when the mouse is dragged, after responding `YES` to a previous `mouseDown`: 44 call. 45 46 @param evt {SC.Event} the mousemove event 47 @returns {void} 48 */ 49 mouseDragged: function(evt) {}, 50 51 /** 52 Called when the mouse exits the view and the root responder is not in a 53 drag session. 54 55 @param evt {SC.Event} the mousemove event 56 @returns {void} 57 */ 58 mouseExited: function(evt) {}, 59 60 /** 61 Called when the mouse enters the view and the root responder is not in a 62 drag session. 63 64 @param evt {SC.Event} the mousemove event 65 @returns {void} 66 */ 67 mouseEntered: function(evt) {}, 68 69 /** 70 Called when the mouse moves within the view and the root responder is not in a 71 drag session. 72 73 @param evt {SC.Event} the mousemove event 74 @returns {void} 75 */ 76 mouseMoved: function(evt) {}, 77 78 /** 79 Called when a contextmenu event is triggered. Used to disable contextmenu 80 per view. 81 82 @param evt {SC.Event} the contextmenu event 83 @returns {void} 84 */ 85 contextMenu: function(evt) {}, 86 87 /** 88 Called when a selectstart event in IE is triggered. **ONLY IE** 89 We use it to disable IE accelerators and text selection 90 91 @param evt {SC.Event} the selectstart event 92 @returns {void} 93 */ 94 selectStart: function(evt) {}, 95 96 // ....................................................................... 97 // Touch Event Handlers 98 // 99 100 /** 101 Called when a touch begins. Capturing a touch is a special case behavior that allows for the 102 nesting of touch capable views. In some situations, an outer view may want to capture a touch 103 *before* the inner view acts on it. For example, a container view may want to act on swipes or 104 pinches, while the inner view may only respond to taps. If the normal event path was followed, 105 the inner view would get the `touchStart` event and by accepting it, would inadvertently prevent 106 the outer view from being able to act on it. 107 108 For this reason, when a touch begins, each view from the top-down has a chance to capture a 109 touch first, before it is passed to the bottom-most target view. For example, SC.ScrollView 110 captures touches so that it can determine if the touch is the beginning of a swipe or pinch. If 111 the touch does become one of these gestures, SC.ScrollView can act on it. However, if the touch 112 doesn't become one of these gestures, SC.ScrollView understands that it needs to pass the touch 113 to its children. 114 115 Therefore, implementors of `captureTouch` are expected to release the touch if they won't use it 116 by calling the touch's `captureTouch` method and passing themself as the new starting point 117 (capturing will continue from the implementor onward as it would have if the implementor hadn't 118 temporarily captured it). 119 120 Note, `captureTouch` is only meaningful for container type views where their children may 121 handle touches as well. For most controls that want to handle touch, there is no reason to 122 capture a touch, because they don't have any children. For these views, simply use the 123 `touchStart`, `touchesDragged`, `touchCancelled` and `touchEnd` methods. 124 125 @param touch {SC.Touch} the touch 126 @returns {Boolean} YES to claim the touch and receive touchStart, NO otherwise 127 @see SC.Touch#captureTouch 128 */ 129 captureTouch: function (touch) {}, 130 131 /** 132 Called when a touch previously claimed by returning `true` from `touchStart` is cancelled. 133 134 @param touch {SC.Touch} the touch 135 @returns {void} 136 */ 137 touchCancelled: function (touch) {}, 138 139 /** 140 Called when an active touch moves. The touches array contains all of the touches that this view 141 has claimed by returning `true` from `touchStart`. 142 143 @param evt {SC.Event} the event 144 @param touches {Array} the touches 145 @returns {void} 146 */ 147 touchesDragged: function (evt, touches) {}, 148 149 /** 150 Called when a touch previously claimed by returning `true` from `touchStart` ends. 151 152 @param touch {SC.Touch} the touch 153 @returns {void} 154 */ 155 touchEnd: function (touch) {}, 156 157 /** 158 Called when a touch begins. You must return `YES` to receive `touchesDragged` and `touchEnd` in 159 the future. 160 161 @param touch {SC.Touch} the touch 162 @returns {Boolean} YES to receive additional touch events, NO otherwise 163 */ 164 touchStart: function (touch) {}, 165 166 // ....................................................................... 167 // Keyboard Event Handlers 168 // 169 // These methods are called by the input manager in response to keyboard 170 // events. Most of these methods are defined here for you, but not actually 171 // implemented in code. 172 173 /** 174 Insert the text or act on the key. 175 176 @param {String} the text to insert or respond to 177 @returns {Boolean} YES if you handled the method; NO otherwise 178 */ 179 insertText: function(text) {}, 180 181 /** 182 When the user presses a key-combination event, this will be called so you 183 can run the command. 184 185 @param charCode {String} the character code 186 @param evt {SC.Event} the keydown event 187 @returns {Boolean} YES if you handled the method; NO otherwise 188 */ 189 performKeyEquivalent: function(charCode, evt) { return false; }, 190 191 /** 192 This method is called if no other view in the current view hierarchy is 193 bound to the escape or command-. key equivalent. You can use this to 194 cancel whatever operation is running. 195 196 @param sender {Object} the object that triggered; may be null 197 @param evt {SC.Event} the event that triggered the method 198 @returns {Boolean} YES if you handle the event; NO otherwise 199 */ 200 cancel: function(sender, evt) {}, 201 202 /** 203 Delete the current selection or delete one element backward from the 204 current selection. 205 206 @param sender {Object} the object that triggered the method; may be null 207 @param evt {SC.Event} the event that triggered the method; may be null 208 @returns {Boolean} YES if you handle the event; NO otherwise 209 */ 210 deleteBackward: function(sender, evt) {}, 211 212 /** 213 Delete the current selection or delete one element forward from the 214 current selection. 215 216 @param sender {Object} the object that triggered the method; may be null 217 @param evt {SC.Event} the event that triggered the method; may be null 218 @returns {Boolean} YES if you handle the event; NO otherwise 219 */ 220 deleteForward: function(sender, evt) {}, 221 222 /** 223 A field editor might respond by selecting the field before it. 224 225 @param sender {Object} the object that triggered the method; may be null 226 @param evt {SC.Event} the event that triggered the method; may be null 227 @returns {Boolean} YES if you handle the event; NO otherwise 228 */ 229 insertBacktab: function(sender, evt) {}, 230 231 /** 232 Insert a newline character or end editing of the receiver. 233 234 @param sender {Object} the object that triggered the method; may be null 235 @param evt {SC.Event} the event that triggered the method; may be null 236 @returns {Boolean} YES if you handle the event; NO otherwise 237 */ 238 insertNewline: function(sender, evt) {}, 239 240 /** 241 Insert a tab or move forward to the next field. 242 243 @param sender {Object} the object that triggered the method; may be null 244 @param evt {SC.Event} the event that triggered the method; may be null 245 @returns {Boolean} YES if you handle the event; NO otherwise 246 */ 247 insertTab: function(sender, evt) {}, 248 249 /** 250 Move insertion point/selection backward one. (i.e. left arrow key) 251 252 @param sender {Object} the object that triggered the method; may be null 253 @param evt {SC.Event} the event that triggered the method; may be null 254 @returns {Boolean} YES if you handle the event; NO otherwise 255 */ 256 moveLeft: function(sender, evt) {}, 257 258 /** 259 Move the insertion point/selection forward one (i.e. right arrow key) 260 in left-to-right text, this could be the left arrow key. 261 262 @param sender {Object} the object that triggered the method; may be null 263 @param evt {SC.Event} the event that triggered the method; may be null 264 @returns {Boolean} YES if you handle the event; NO otherwise 265 */ 266 moveRight: function(sender, evt) {}, 267 268 /** 269 Move the insertion point/selection up one (i.e. up arrow key) 270 271 @param sender {Object} the object that triggered the method; may be null 272 @param evt {SC.Event} the event that triggered the method; may be null 273 @returns {Boolean} YES if you handle the event; NO otherwise 274 */ 275 moveUp: function(sender, evt) {}, 276 277 /** 278 Move the insertion point/selection down one (i.e. down arrow key) 279 280 @param sender {Object} the object that triggered the method; may be null 281 @param evt {SC.Event} the event that triggered the method; may be null 282 @returns {Boolean} YES if you handle the event; NO otherwise 283 */ 284 moveDown: function(sender, evt) {}, 285 286 /** 287 Move left, extending the selection. - shift || alt 288 289 @param sender {Object} the object that triggered the method; may be null 290 @param evt {SC.Event} the event that triggered the method; may be null 291 @returns {Boolean} YES if you handle the event; NO otherwise 292 */ 293 moveLeftAndModifySelection: function(sender, evt) {}, 294 295 /** 296 Move right, extending the seleciton - shift || alt 297 298 @param sender {Object} the object that triggered the method; may be null 299 @param evt {SC.Event} the event that triggered the method; may be null 300 @returns {Boolean} YES if you handle the event; NO otherwise 301 */ 302 moveRightAndModifySelection: function(sender, evt) {}, 303 304 /** 305 Move up, extending the selection - shift || alt 306 307 @param sender {Object} the object that triggered the method; may be null 308 @param evt {SC.Event} the event that triggered the method; may be null 309 @returns {Boolean} YES if you handle the event; NO otherwise 310 */ 311 moveUpAndModifySelection: function(sender, evt) {}, 312 313 /** 314 Move down, extending selection - shift || alt 315 316 @param sender {Object} the object that triggered the method; may be null 317 @param evt {SC.Event} the event that triggered the method; may be null 318 @returns {Boolean} YES if you handle the event; NO otherwise 319 */ 320 moveDownAndModifySelection: function(sender, evt) {}, 321 322 /** 323 Move insertion point/selection to beginning of document. 324 325 @param sender {Object} the object that triggered the method; may be null 326 @param evt {SC.Event} the event that triggered the method; may be null 327 @returns {Boolean} YES if you handle the event; NO otherwise 328 */ 329 moveToBeginningOfDocument: function(sender, evt) {}, 330 331 /** 332 Move insertion point/selection to end of document. 333 334 @param sender {Object} the object that triggered the method; may be null 335 @param evt {SC.Event} the event that triggered the method; may be null 336 @returns {Boolean} YES if you handle the event; NO otherwise 337 */ 338 moveToEndOfDocument: function(sender, evt) {}, 339 340 /** 341 Page down 342 343 @param sender {Object} the object that triggered the method; may be null 344 @param evt {SC.Event} the event that triggered the method; may be null 345 @returns {Boolean} YES if you handle the event; NO otherwise 346 */ 347 pageDown: function(sender, evt) {}, 348 349 /** 350 Page up 351 352 @param sender {Object} the object that triggered the method; may be null 353 @param evt {SC.Event} the event that triggered the method; may be null 354 @returns {Boolean} YES if you handle the event; NO otherwise 355 */ 356 pageUp: function(sender, evt) {}, 357 358 /** 359 Select all 360 361 @param sender {Object} the object that triggered the method; may be null 362 @param evt {SC.Event} the event that triggered the method; may be null 363 @returns {Boolean} YES if you handle the event; NO otherwise 364 */ 365 selectAll: function(sender, evt) {} 366 367 }; 368