PAGestureAssistant 0.2.10

PAGestureAssistant 0.2.10

TestsTested
LangLanguage Obj-CObjective C
License MIT
ReleasedLast Release Jun 2016

Maintained by Pedro Almeida.




Possibilities iPad multi-window

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.

Behaviors

This pod has two distinct behaviors:

Assistant Mode

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.

Tutorial Mode

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.

Usage

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 call it 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;

Appearance

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"]];

Examples

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");

        }];
    }];
}];

Requirements

  • iOS 7.0+
  • If you install it manually, you must also copy FrameAccessor.

Installation

PAGestureAssistant is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod "PAGestureAssistant"

Author

Pedro Almeida, @ipedro

Credits

Hand icon by Zach Blevins. The category implementation was inspired by Bryce Buchanan's swizzling method.

License

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.