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