PAGestureAssistant is a drop-in UIViewController category for showing interaction tips and tutorials to users that has predefined gestures for convenience and also the ability to define your own.
This pod has two distinct behaviors:
Ideal for non-obvious usage patterns, like swiping down to dismiss a view.
Every time the user idles for longer than the defined interval the animation kicks in, and any user interaction passes through to the views below. To achieve this behavior, use any of the showGestureAssistant
methods without a completion block.
Ideal for teaching users intricate flows.
After the defined interval the animation will show only once, and any user interaction will be blocked. To achieve this behavior simply pass a completion block (even an empty one) to any of the showGestureAssistant
methods.
To run the example project, clone the repo, and run pod install
from the Example directory first.
Then, in your viewDidAppear
set your assistant. Don't try to call if before
- (void)viewDidAppear:(BOOL)animated
{
[super viewDidAppear:animated];
// Shows a tap gesture animation in the view's center
// everytime the user idles for more than 5 seconds.
[self showGestureAssistantForTap:PAGestureAssistantTapSingle
view:self.view
text:@"Tap here to begin"
afterIdleInterval:5];
}
That's it!
You can choose from a set of predefined animations from the list below, or define your own custom swipe with a startPoint
and endPoint
(check tutorial example below).
// Tap animations
PAGestureAssistantTapSingle
PAGestureAssistantTapLongPress
PAGestureAssistantTapDouble
// Swipe animations
PAGestureAssistantSwipeDirectonUp
PAGestureAssistantSwipeDirectonDown
PAGestureAssistantSwipeDirectonLeft
PAGestureAssistantSwipeDirectonRight
You can also disable the assistant anytime (but shouldn't really need to).
- (void)stopGestureAssistant;
- (void)stopGestureAssistantWithCompletion:(PAGestureCompletion)completion;
You can customize the following properties, and/or use a NSAttributedString
to format text as you wish.
/* Sets a custom overlay color */
[[PAGestureAssistant appearance] setBackgroundColor:[UIColor colorWithWhite:1 alpha:0.8f]];
/* Sets a custom text color */
[[PAGestureAssistant appearance] setTextColor:[UIColor darkGrayColor]];
/* Sets the gesture view color */
[[PAGestureAssistant appearance] setTapColor:self.view.tintColor];
/* Sets a custom image for the gesture view */
[[PAGestureAssistant appearance] setTapImage:[UIImage imageNamed:@"imageName"]];
Tutorial Example:
/* Chain multiple calls to achieve a tutorial effect */
// First show a custom swipe...
[self showGestureAssistantForSwipeWithStartPoint:CGPointMake(60, 60)
endPoint:self.view.center
text:@"This is a custom swipe"
afterIdleInterval:0
completion:^(BOOL finished) {
// ...then a tap on a button...
[self showGestureAssistantForTap:PAGestureAssistantTapSingle
view:self.button
text:@"This is a single tap"
afterIdleInterval:0
completion:^(BOOL finished) {
// ...and a swipe up gesture
[self showGestureAssistantForSwipeDirection:PAGestureAssistantSwipeDirectonUp
text:@"This is a swipe up"
afterIdleInterval:0
completion:^(BOOL finished) {
// do something
NSLog(@"Tutorial complete");
}];
}];
}];
- iOS 7.0+
- If you install it manually, you must also copy FrameAccessor.
PAGestureAssistant is available through CocoaPods. To install it, simply add the following line to your Podfile:
pod "PAGestureAssistant"
Pedro Almeida, @ipedro
Hand icon by Zach Blevins. The category implementation was inspired by Bryce Buchanan's swizzling method.
PAGestureAssistant is available under the MIT license.
Copyright (c) 2016 Pedro Almeida.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.