Skip to content
🎀 A simple cross-platform toolbar/custom input accessory view library for iOS & macOS.
Swift Ruby Makefile Other
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.readme-assets
Demos Refactor stored properties to computed, fix dark mode, and refactor. Aug 10, 2019
Ribbon.xcodeproj Refactor stored properties to computed, fix dark mode, and refactor. Aug 10, 2019
Ribbon Refactor stored properties to computed, fix dark mode, and refactor. Aug 10, 2019
Scripts Move code coverage conversion script to script directory. Aug 8, 2019
Unit Tests Codebeat refactoring. Aug 9, 2019
.codebeatsettings Add CodeBeat metrics customization configuration file. Aug 9, 2019
.gitignore (Real) initial commit Aug 8, 2019
.swiftlint.yml Add supporting files to xcode project. Aug 9, 2019
.travis.yml Add some polish. Aug 8, 2019
LICENSE Initial commit Aug 7, 2019
Makefile Move code coverage conversion script to script directory. Aug 8, 2019
README.md Add platform badge. Aug 10, 2019
Ribbon.podspec
iOS13.xcconfig Update iOS 13 build/conditionals. Aug 8, 2019
sonar-project.properties Fix Travis/SonarQube pt. 3 Aug 8, 2019

README.md

Ribbon 🎀

Supported Platforms Carthage compatible Pod Version codebeat badge Swift Version GitHub license PRs Welcome

Header

A simple cross-platform toolbar/custom input accessory view library for iOS & macOS.
Written in Swift.


Looking for...

  • A type-safe, XPC-available SourceKitten (SourceKit) interface with some sugar? Check out Sylvester 😼.
  • A Floating Action Button for macOS? Check out Fab. 🛍️.
  • An Expanding Bubble Text Field for macOS? Check out BubbleTextField 💬.
  • An integrated spotlight-based onboarding and help library for macOS? Check out Enlighten 💡.

Features

🎡 Try: Includes an iOS & macOS demo.

  • Provide items either programmatically or from a JSON configuration file.
  • Dark mode.
  • + more!

iOS

macOS

  • Supports push, action, & segmented control toolbar items.
  • Provides NSMenuItems for each item.

Requirements

  • iOS 10.0+ (12.0+ for dark mode)
  • macOS 10.12+ (10.13+ for full functionality)

Installation

Ribbon is available for installation using Carthage or CocoaPods.

Carthage

github "chriszielinski/Ribbon"

CocoaPods

pod "Ribbon"

iOS 13

Building for iOS 13 requires Xcode 11 and modifying iOS13.xcconfig:

// Uncomment to build Ribbon for iOS 13.
//
// - Note: Requires Xcode 11.

SWIFT_ACTIVE_COMPILATION_CONDITIONS = $(inherited) IOS13

Usage

There are two ways of integrating Ribbon into your project:

Configuration File

🔥 The recommended approach.

The configuration file makes for a quick & easy integration. The default configuration filename is ribbon-configuration.json and should be copied into the target's bundle resources (in the Copy Bundle Resources build phase).

The JSON below defines a single action item and toolbar configuration—which is only relevant for the macOS platform.

🧐 See: Demos/Shared/ribbon-configuration.json for a more comprehensive example.

{
    "items": [
        {
            "action": "actionItemHandler",
            "controlKind": "action",
            "identifier": "action-item-identifier",
            "imageName": "NSActionTemplate",
            "keyEquivalent": "a",
            "keyEquivalentModifier": ["command", "shift"],
            "title": "Action Item",
            "toolTip": "The action button's tool-tip.",
            "subitems": [
                {
                    "action": "firstActionSubitemHandler",
                    "identifier": "first-action-subitem",
                    "imageName": "hand.thumbsup",
                    "keyEquivalent": "1",
                    "keyEquivalentModifier": ["command"],
                    "title": "First Action Subitem",
                    "toolTip": "The first action's tool-tip."
                },
                {
                    "action": "secondActionSubitemHandler",
                    "identifier": "second-action-subitem",
                    "imageName": "hand.thumbsdown",
                    "keyEquivalent": "2",
                    "keyEquivalentModifier": ["command"],
                    "title": "Second Action Subitem",
                    "toolTip": "The second action's tool-tip."
                }
            ]
        }
    ],
    "toolbar": {
        "displayMode": "iconOnly",
        "sizeMode": "regular",
        "identifier": "toolbar-identifier",
        "defaultItems" : ["NSToolbarFlexibleSpaceItem", "action-item-identifier"]
    }
}

Integration into your view controller is as simple as:

📌 Note: The code below is an abstraction and will not compile.

import Ribbon

class YourViewController ... {

    ...
    
    var ribbon: Ribbon!

    override func viewDidLoad() {
        ribbon = try! Ribbon.loadFromMainBundle(target: self)

        #if canImport(UIKit)
        textView.inputAccessoryView = ribbon
        #endif
    }
    
    #if canImport(AppKit)
    override func viewWillAppear() {
        view.window?.toolbar = ribbon.toolbar

        super.viewWillAppear()
    }
    #endif
    
    @objc
    func actionItemHandler() { }

    @objc
    func firstActionSubitemHandler() { }

    @objc
    func secondActionSubitemHandler() { }

}

Programmatically

📌 Note: The code below is an abstraction and will not compile.

import Ribbon

class YourViewController ... {

    ...
    
    var ribbon: Ribbon!

    override func viewDidLoad() {
        let firstActionSubitem = RibbonItem(subItemTitle: "First Action Subitem")
        firstActionSubitem.action = #selector(firstActionSubitemHandler)
        let secondActionSubitem = RibbonItem(subItemTitle: "Second Action Subitem")
        secondActionSubitem.action = #selector(secondActionSubitemHandler)

        let actionItem = RibbonItem(controlKind: .action,
                                    title: "Action Item",
                                    subitems: [firstActionSubitem, secondActionSubitem])
        actionItem.action = #selector(actionItemHandler)
        ribbon = Ribbon(items: [actionItem], target: self)

        #if canImport(UIKit)
        textView.inputAccessoryView = ribbon
        #endif
    }
    
    #if canImport(AppKit)
    override func viewWillAppear() {
        view.window?.toolbar = ribbon.toolbar

        super.viewWillAppear()
    }
    #endif
    
    @objc
    func actionItemHandler() { }

    @objc
    func firstActionSubitemHandler() { }

    @objc
    func secondActionSubitemHandler() { }

}

// ToDo:

  • Add documentation.
  • Implement UIKeyCommand.

Community

  • Found a bug? Open an issue.
  • Feature idea? Open an issue. Do it yourself & PR when done 😅 (or you can open an issue 🙄).
  • Want to contribute? Submit a pull request.

Acknowledgements

Contributors

Frameworks & Libraries

Ribbon depends on the wonderful contributions of the Swift community, namely:

License

Ribbon is available under the MIT license, see the LICENSE file for more information.

You can’t perform that action at this time.