/BlocksKit/UIGestureRecognizer+BlocksKit.h

  1//
  2//  UIGestureRecognizer+BlocksKit.h
  3//  %PROJECT
  4//
  5
  6#import "BKGlobals.h"
  7
  8/** Block functionality for UIGestureRecognizer.
  9
 10 Use of the delay property is pretty straightforward, although
 11 cancellation might be a little harder to swallow.  An example
 12 follows:
 13	 UITapGestureRecognizer *singleTap = [UITapGestureRecognizer recognizerWithHandler:^(id sender) {
 14		 NSLog(@"Single tap.");
 15	 } delay:0.18];
 16	 [self addGestureRecognizer:singleTap];
 17 
 18	 UITapGestureRecognizer *doubleTap = [UITapGestureRecognizer recognizerWithHandler:^(id sender) {
 19		[singleTap cancel];
 20		NSLog(@"Double tap.");
 21	 }];
 22	 doubleTap.numberOfTapsRequired = 2;
 23	 [self addGestureRecognizer:doubleTap];
 24
 25 Believe it or not, the above code is fully memory-safe and efficient.  Eagle-eyed coders
 26 will notice that this setup emulates UIGestureRecognizer's requireGestureRecognizerToFail:,
 27 and, yes, it totally apes it.  Not only is this setup much faster on the user's end of
 28 things, it is more flexible and allows for much more complicated setups.
 29
 30 Includes code by the following:
 31
 32 - Kevin O'Neill.  <https://github.com/kevinoneill>. 2011. BSD.
 33 - Zach Waldowski. <https://github.com/zwaldowski>.  2011. MIT.
 34
 35 @warning UIGestureRecognizer is only available on iOS or in a Mac app using Chameleon.
 36 
 37 @warning It is not recommended to use the Apple-supplied locationInView and state
 38 methods on a *delayed* block-backed gesture recognizer, as these properties are
 39 likely to have been cleared by the time by the block fires.  It is instead recommended
 40 to use the arguments provided to the block in BlocksKit builds after 15 Jun. 2011.
 41 */
 42
 43@interface UIGestureRecognizer (BlocksKit)
 44
 45/** An autoreleased gesture recognizer that will, on firing, call
 46 the given block asynchronously after a number of seconds.
 47
 48 @return An autoreleased instance of a concrete UIGestureRecognizer subclass, or `nil`.
 49 @param block The block which handles an executed gesture.
 50 @param delay A number of seconds after which the block will fire.
 51 */
 52+ (id)recognizerWithHandler:(BKGestureRecognizerBlock)block delay:(NSTimeInterval)delay;
 53
 54/** Initializes an allocated gesture recognizer that will call the given block
 55 after a given delay.
 56 
 57 An alternative to the designated initializer.
 58 
 59 @return An initialized instance of a concrete UIGestureRecognizer subclass or `nil`.
 60 @param block The block which handles an executed gesture.
 61 @param delay A number of seconds after which the block will fire.
 62 */
 63- (id)initWithHandler:(BKGestureRecognizerBlock)block delay:(NSTimeInterval)delay;
 64
 65/** An autoreleased gesture recognizer that will call the given block.
 66 
 67 For convenience and compatibility reasons, this method is indentical
 68 to using recognizerWithHandler:delay: with a delay of 0.0.
 69  
 70 @return An initialized and autoreleased instance of a concrete UIGestureRecognizer
 71 subclass, or `nil`.
 72 @param block The block which handles an executed gesture.
 73 */
 74+ (id)recognizerWithHandler:(BKGestureRecognizerBlock)block;
 75
 76/** Initializes an allocated gesture recognizer that will call the given block.
 77 
 78 This method is indentical to calling initWithHandler:delay: with a delay of 0.0.
 79
 80 @return An initialized instance of a concrete UIGestureRecognizer subclass or `nil`.
 81 @param block The block which handles an executed gesture.
 82 */
 83- (id)initWithHandler:(BKGestureRecognizerBlock)block;
 84
 85/** Allows the block that will be fired by the gesture recognizer
 86 to be modified after the fact.
 87 */
 88@property (nonatomic, copy) BKGestureRecognizerBlock handler;
 89
 90/** Allows the length of the delay after which the gesture
 91 recognizer will be fired to modify.
 92 */
 93@property (nonatomic) NSTimeInterval delay;
 94
 95/** If the recognizer happens to be fired, calling this method
 96 will stop it from firing, but only if a delay is set.
 97
 98 @warning This method is not for arbitrarily canceling the
 99 firing of a recognizer, but will only function for a block
100 handler *after the recognizer has already been fired*.  Be
101 sure to make your delay times accomodate this likelihood.
102 */
103- (void)cancel;
104
105@end