carabina / pushmenu Goto Github PK

Installation • Usage • 7 Options Limit • License

PushMenu is a revolutionary iOS component that can easily be added to any UIView. PushMenu displays options which users can select without lifting a finger, either by using 3D Touch or sliding their finger across the menu. A cell in the menu is highlighted based on the amount of force the user applies to his screen. After a delay, that highlighted cell gets selected and its associated action gets called. PushMenu feels right at home with the iOS ecosystem and is a new, yet comfortable approach to displaying menu options to users.

Note: PushMenu works on all devices - users with devices that don't support 3D Touch can simply use the backup sliding mechanism to choose options.

Most simulators don't have 3D Touch capabilites, it's recommended to run the example project on a device.

The first demo is of PushMenu with 3D Touch in action. The other demos are of the backup sliding mechanism.

import PushMenu

class MyViewController: UIViewController {

    let photo = UIView()

    override func viewDidLoad() {
        super.viewDidLoad()
        
        photo.pushMenu.isEnabled = true
        photo.pushMenu.addCell(title: "Cancel", type: .cancel, action: nil)
        photo.pushMenu.addCell(title: "Save to Library", type: .normal, action: {
            // ...
        })
    }
}

PushMenu is customizable. That means you can configure:

• .opacity
• .cellHeight
• .font
• .style (.light or .dark)
• .selectionDelay

PushMenu requires iOS 9+ and is compatible with Swift 3 projects.

• Installation for CocoaPods:

platform :ios, '9.0'
target 'ProjectName' do
use_frameworks!

pod 'PushMenu'

end

• Or drag and drop the PushMenu framework into your project.

And import PushMenu in the files you'd like to use it.

It's recommended to look through the example project—it has detailed documentation of everything PushMenu has to offer.

Note: throughout this document, photo will act as the view being animated. You can use PushMenu on any instance of a UIView or UIView subclass, such as UILabel, UITextField, UIButton, etc.

Using PushMenu is easy.

1. Enable PushMenu for the view.

2. Customize your view's PushMenu.

3. Add option cells.

Enabling PushMenu for a view automatically creates a new instance of a PushMenu and attaches a PushMenuGestureRecognizer to the view.

Note: You must enable pushMenu first before adding cells or customizing it (see below.)

photo.pushMenu.isEnabled = true

Setting this value to false will result in the PushMenu instance and PushMenuGestureRecognizer being removed.

PushMenu wouldn't be cool if you couldn't customize it for your use case.

Style: .light or .dark (more themes will be available in future releases, feel free to contribute and add your own themes!)

photoView.pushMenu.style = .dark // default is .light

Opacity: the alpha value of the cells' background colors.

photoView.pushMenu.opacity = 0.75 // default is 1.0

Cell Height: the height for each option cell.

photoView.pushMenu.cellHeight = 45 // default is 55

Font: the font for the cells' title labels.

photoView.pushMenu.font = UIFont.systemFont(ofSize: 16, weight: UIFontWeightMedium) // default is UIFont.systemFont(ofSize: 18, weight: UIFontWeightMedium)

Selection Delay: how long it takes (in seconds) for a highlighted cell to become selected.

photoView.pushMenu.selectionDelay = 0.7 // default is 0.45

PushMenu can only have 7 options - why?

All PushMenus should have a cancel option first. Cancel options don't become selected, giving users as much time as they need to decide what option they want. Apple says the average force is ~ 1.0, the amount of force that is needed to highlight the first cell, which is why it's important that the first cell is of cancel type.

photoView.pushMenu.addCell(title: "Cancel", type: .cancel, action: nil)

Then you can add normal options:

photoView.pushMenu.addCell(title: "Save to Library", type: .normal, action: {
    // this closure gets called immediately after this cell is selected
})

... or destructive options:

photoView.pushMenu.addCell(title: "Delete Image", type: .destructive, action: {
    // ...
})

Most devices that have 3D Touch capabilites have a maximum force of 6.6666667, and Apple says that an average touch's force is ~1.0. PushMenu was built with this in mind, so each option cell of a menu takes 1 force unit. Meaning a force of 0-1 will highlight the first cell, a force of 1-2 will highlight the second cell, and so on until the 7th cell which gets highlighted from a force of 6 or above. A force unit of 1 is small, yet comfortable enough for a user to get a feel of what amount of pressure it takes to get to a certain cell.

Option + click on any of PushMenu's properties/methods for detailed documentation.

PushMenu uses the MIT license. Please file an issue if you have any questions or if you'd like to share how you're using PushMenu.

PushMenu is at its first stage, but is robust and powerful enough to be used in production-ready apps. Please feel free to submit pull requests, even if your addition/revision is minor. Here is a list of things to work on for future releases:

• more themes besides .light and .dark

Contact me by email [email protected], or by twitter @sdrzn. Please create an issue if you come across a bug or would like a feature to be added.

Touch icon by iconsphere from the Noun Project