Skip to content

Latest commit

 

History

History
471 lines (361 loc) · 15.9 KB

README.md

File metadata and controls

471 lines (361 loc) · 15.9 KB
Raw

FFPopup

CI Status Codecov Status Cocoapods Version Carthage compatible Platform MIT License FFPopup Issues Twitter

FFPopup is a lightweight library for presenting custom views as a popup.

Bounce from Top & Bounce to Bottom Bounce from Top & Bounce to Top Bounce in & Bounce out Grow in & Shrink out Bounce from Bottom & Slide to Bottom Slide from Bottom & Slide to Bottom

Features

  • Support several popup show types

    • None
    • Fade In
    • Grow In
    • Shrink In
    • Slide In from top, bottom, left, right
    • Bounce In from top, bottom, left, right, center
    • Support custom

  • Support several popup dismiss types

    • None
    • Fade Out
    • Grow Out
    • Shrink Out
    • Slide Out to top, bottom, left, right
    • Bounce Out to top, bottom, left, right, center
    • Support custom

  • Layout the popup in the horizontal direction

    • Left
    • Right
    • Center
    • Left of center
    • Right of center
    • Support custom

  • Layout the popup in the vertical direction

    • Top
    • Bottom
    • Center
    • Above center
    • Below center
    • Support custom

  • Controlled whether to allow interaction with the underlying view

    • Allow interaction with underlying view
    • Don't allow interaction with underlying view
    • Don't allow interaction with underlying view, dim background
    • Don't allow interaction with underlying view, blur background
    • Support custom

  • Others

    • Complete Documentation

Requirements

  • iOS 8.0+ / macOS 10.13.6+
  • Xcode 10.1 (10B61) +

Example

To run the FFPopup project, clone the Repo, and start FFPopup in Xcode.

$ git clone https://github.com/JonyFang/FFPopup.git
$ cd FFPopup
$ cd Shell && sh install-bundle.sh && sh install-pods.sh && cd ..
$ open FFPopup.xcworkspace

Installation

There are three ways to use FFPopup in your project:

  • Installation with CocoaPods
  • Installation with Carthage
  • Manually install

CocoaPods

CocoaPods is a dependency manager, which automates and simplifies the process of using 3rd-party libraries like FFPopup in your projects. First, add the following line to your Podfile:

pod 'FFPopup'

If you want to use the latest features of FFPopup use normal external source dependencies.

pod 'FFPopup', :git => 'https://github.com/JonyFang/FFPopup.git'

This pulls from the master branch directly.

Second, install FFPopup into your project:

$ pod install

Carthage

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.

You can install Carthage with Homebrew using the following command:

$ brew update
$ brew install carthage

To integrate FFPopup into your Xcode project using Carthage, specify it in your Cartfile:

github "JonyFang/FFPopup"

Run the following command to build the framework:

$ carthage update

Drag the built FFPopup.framework binaries from Carthage/Build/iOS into your application’s Xcode project.

On your application targets’ Build Phases settings tab, click the + icon and choose New Run Script Phase. Create a Run Script in which you specify your shell (ex: /bin/sh), add the following contents to the script area below the shell:

/usr/local/bin/carthage copy-frameworks

Add the following paths to the frameworks you want to use under Input Files.

$(SRCROOT)/Carthage/Build/iOS/FFPopup.framework

For an in depth guide, read on from Adding frameworks to an application

Manually

Alternatively you can directly add the FFPopup.h and FFPopup.m source files to your project.

  • Download the latest code version or add the repository as a git submodule to your git-tracked project.
  • Open your project in Xcode, then drag and drop FFPopup.h and FFPopup.m onto your project (use the "Product Navigator view"). Make sure to select Copy items when asked if you extracted the code archive outside of your project.
  • Include FFPopup wherever you need it with #import "FFPopup.h".

Swift

Even though FFPopup is written in Objective-C, it can be used in Swift with no hassle. If you use CocoaPods add the following line to your Podfile:

use_frameworks!

If you added FFPopup manually, just add a bridging header file to your project with the FFPopup header included.

Usage

Import the library where you want to use it.

  • Objective-C
#import <FFPopup.h>

- (void)showPopup {
    FFPopup *popup = [FFPopup popupWithContentView:self.contentView showType:FFPopupShowType_BounceIn dismissType:FFPopupDismissType_ShrinkOut maskType:FFPopupMaskType_Dimmed dismissOnBackgroundTouch:YES dismissOnContentTouch:NO];
    FFPopupLayout layout = FFPopupLayoutMake(FFPopupHorizontalLayout_Center, FFPopupVerticalLayout_Center);
    [popup showWithLayout:layout];
}
  • Swift
import FFPopup

func showPopup() {
    let popup = FFPopup(contentView: self.contentView, showType: .bounceIn, dismissType: .shrinkOut, maskType: .dimmed, dismissOnBackgroundTouch: true, dismissOnContentTouch: false)
    let layout = FFPopupLayout(horizontal: .center, vertical: .center)
    popup.show(layout: layout)
}

Customization

1.FFPopupShowType

Animation transition for presenting contentView. Controlled how the popup will be presented.

The default value is FFPopupShowType_BounceInFromTop.

FFPopupShowType
FFPopupShowType_None
FFPopupShowType_FadeIn
FFPopupShowType_GrowIn
FFPopupShowType_ShrinkIn
FFPopupShowType_SlideInFromTop
FFPopupShowType_SlideInFromBottom
FFPopupShowType_SlideInFromLeft
FFPopupShowType_SlideInFromRight
FFPopupShowType_BounceIn
FFPopupShowType_BounceInFromTop
FFPopupShowType_BounceInFromBottom
FFPopupShowType_BounceInFromLeft
FFPopupShowType_BounceInFromRight

2.FFPopupDismissType

Animation transition for dismissing contentView. Controlled how the popup will be dismissed.

The default value is FFPopupDismissType_BounceOutToBottom.

FFPopupDismissType
FFPopupDismissType_None
FFPopupDismissType_FadeOut
FFPopupDismissType_GrowOut
FFPopupDismissType_ShrinkOut
FFPopupDismissType_SlideOutToTop
FFPopupDismissType_SlideOutToBottom
FFPopupDismissType_SlideOutToLeft
FFPopupDismissType_SlideOutToRight
FFPopupDismissType_BounceOut
FFPopupDismissType_BounceOutToTop
FFPopupDismissType_BounceOutToBottom
FFPopupDismissType_BounceOutToLeft
FFPopupDismissType_BounceOutToRight

3.FFPopupMaskType

Mask prevents background touches from passing to underlying views. Controlled whether to allow interaction with the underlying view.

The default value is FFPopupMaskType_Dimmed.

FFPopupMaskType
FFPopupMaskType_None
FFPopupMaskType_Clear
FFPopupMaskType_Dimmed

4.Other Properties

Property Name Description Default Value
dimmedMaskAlpha Overrides alpha value for dimmed mask. 0.5
showInDuration Overrides animation duration for show in. 0.15
dismissOutDuration Overrides animation duration for dismiss out. 0.15
shouldDismissOnBackgroundTouch If YES, the popup will dismiss when background is touched. YES
shouldDismissOnContentTouch If YES, the popup will dismiss when content view is touched. NO

5.Blocks

/**
 A block to be executed when showing animation started.
 The default value is nil.
 */
@property (nonatomic, copy, nullable) void(^willStartShowingBlock)(void);

/**
 A block to be executed when showing animation finished.
 The default value is nil.
 */
@property (nonatomic, copy, nullable) void(^didFinishShowingBlock)(void);

/**
 A block to be executed when dismissing animation started.
 The default value is nil.
 */
@property (nonatomic, copy, nullable) void(^willStartDismissingBlock)(void);

/**
 A block to be executed when dismissing animation finished.
 The default value is nil.
 */
@property (nonatomic, copy, nullable) void(^didFinishDismissingBlock)(void);

6.Convenience Initializers

Create a new popup with custom values.

/**
 Convenience Initializers
 Create a new popup with `contentView`.
 */
+ (FFPopup *)popupWithContentView:(UIView *)contentView;

/**
 Convenience Initializers
 Create a new popup with custom values.
 
 @param contentView The view you want to appear in popup.
 @param showType    The default value is `FFPopupShowType_BounceInFromTop`.
 @param dismissType The default value is `FFPopupDismissType_BounceOutToBottom`.
 @param maskType    The default value is `FFPopupMaskType_Dimmed`.
 @param shouldDismissOnBackgroundTouch  The default value is `YES`.
 @param shouldDismissOnContentTouch     The default value is `NO`.
 */
+ (FFPopup *)popupWithContentView:(UIView *)contentView
                         showType:(FFPopupShowType)showType
                      dismissType:(FFPopupDismissType)dismissType
                         maskType:(FFPopupMaskType)maskType
         dismissOnBackgroundTouch:(BOOL)shouldDismissOnBackgroundTouch
            dismissOnContentTouch:(BOOL)shouldDismissOnContentTouch;

7.Showing the Popup

/**
 Show popup with center layout.
 `FFPopupVerticalLayout_Center` & `FFPopupHorizontalLayout_Center`
 Showing animation is determined by `showType`.
 */
- (void)show;

/**
 Show popup with specified layout.
 Showing animation is determined by `showType`.
 */
- (void)showWithLayout:(FFPopupLayout)layout;

/**
 Show and then dismiss popup after `duration`.
 If duration is `0.0` or `less`, it will be considered infinity.
 */
- (void)showWithDuration:(NSTimeInterval)duration;

/**
 Show popup with specified `layout` and then dismissed after `duration`.
 If duration is `0.0` or `less`, it will be considered infinity.
 */
- (void)showWithLayout:(FFPopupLayout)layout duration:(NSTimeInterval)duration;

/**
 Show popup at point in view's coordinate system.
 If view is nil, will use screen base coordinates.
 */
- (void)showAtCenterPoint:(CGPoint)point inView:(UIView *)view;

/**
 Show popup at point in view's coordinate system and then dismissed after duration.
 If view is nil, will use screen base coordinates.
 If duration is `0.0` or `less`, it will be considered infinity.
 */
- (void)showAtCenterPoint:(CGPoint)point inView:(UIView *)view duration:(NSTimeInterval)duration;

8.Dismissing the Popup

/**
 Dismiss popup.
 Use `dismissType` if animated is `YES`.
 */
- (void)dismissAnimated:(BOOL)animated;
 /**
 Dismiss all the popups in the app.
 */
+ (void)dismissAllPopups;

/**
 Dismiss the popup for contentView.
 */
+ (void)dismissPopupForView:(UIView *)view animated:(BOOL)animated;

/**
 Dismiss super popup.
 Iterate over superviews until you find a `FFPopup` and dismiss it.
 */
+ (void)dismissSuperPopupIn:(UIView *)view animated:(BOOL)animated;

TODO List

This is the to-do list for the FFPopup project. You can join us to become a contributor.

  • Support blur option for background mask
  • Support for keyboard show/hide
  • Support for drag-to-dismiss

See the CONTRIBUTING file for contributing guidelines.

Live Demo

My app Time Card -Countdown (Never Forget Important Days) is using FFPopup. You can download it and try it on your multiple devices to experience the effect.

Contributors

This project exists thanks to all the people who contribute. Contribute

Backers

Thank you to all our backers! Your support is really important for the project and encourages us to continue. 🙏 Become a backer

Sponsors

Thank you to all our sponsors! Become a sponsor

License

FFPopup is available under the MIT license. See the LICENSE file for more info.