:warning: Deprecated :warning:

As Swift 3.0 and proposal SE-0069, this library is no longer necessary.

Foundation now provides a Notification struct. Unfortunately, it is not generic like the value type provided by this library, Notification<T, U>, but dealing with the trouble/confusion between the namespaces (Foundation.Notification vs. JSQNotificationObserverKit.Notification) makes this library not worth it.

JSQNotificationObserverKit

Build Status Version Status license MIT codecov Platform Carthage compatible

Generic notifications and observers for Cocoa and CocoaTouch, inspired by objc.io

About

This library aims to provide better semantics regarding notifications and moves the responsibilty of observing and handling notifications to a lightweight, single-purpose object. It also brings type-safety and a cleaner interface to NSNotificationCenter. See objc.io’s snippet #16 on Typed Notification Observers for more information.

Requirements

  • Xcode 7.3+
  • iOS 8.0+
  • OSX 10.10+
  • tvOS 9.1+
  • watchOS 2.0+
  • Swift 2.2

Installation

use_frameworks!

# For latest release in cocoapods
pod 'JSQNotificationObserverKit'

# Feeling adventurous? Get the latest on develop
pod 'JSQNotificationObserverKit', :git => 'https://github.com/jessesquires/JSQNotificationObserverKit.git', :branch => 'develop'

Carthage

github "jessesquires/JSQNotificationObserverKit"

Documentation

Read the docs. Generated with jazzy. Hosted by GitHub Pages. More information on the gh-pages branch.

Getting Started

import JSQNotificationObserverKit

See the included unit tests for more examples and usage.

Example

// Suppose we have a UIView that posts a notification when its size changes
let myView = UIView()

// This notification posts a CGSize value from a UIView sender
let notification = Notification<CGSize, UIView>(name: "NewViewSizeNotif", sender: myView)

// This observer listens for the notification described above
var observer: NotificationObserver<CGSize, UIView>?

// Register observer, start listening for the notification
observer = NotificationObserver(notification) { (value, sender) in
    // handle notification
    // the value and sender are both passed here
}

// Post the notification with the updated CGSize value
notification.post(CGSizeMake(200, 200))

// Unregister observer, stop listening for notifications
observer = nil

Notifications without a sender

Not all notifications are associated with a specific sender object. Here’s how to handle nil sender in JSQNotificationObserverKit. This observer will respond to notifications regardless of the instances sending them.

// This notification posts a string value, the sender is nil
let notification = Notification<String, AnyObject>(name: "StringNotif")

// Post the notification
notification.post("new string")

// Register observer, this handles notifications from *any* sender
var observer: NotificationObserver<String, AnyObject>?
observer = NotificationObserver(notification) { (value, sender) in
    // handle notification
    // the value is passed here, sender is nil
}

// unregister observer, stop listening for notifications
observer = nil

Using a custom queue and notification center

You can optionally pass an NSOperationQueue and NSNotificationCenter. The default values are nil and NSNotificationCenter.defaultCenter(), respectively.

// Initialize an observer and post a notification
// with a custom notification center and operation queue
let c = NSNotificationCenter.defaultCenter()

let q = NSOperationQueue.mainQueue()

let observer = NotificationObserver(n, queue: q, center: c) { (value, sender) in
    // handle notification
}

notification.post(v, center: c)

Notifications without a value

Not all notifications are associated with a specific value. Sometimes notifications are used to simply broadcast an event, for example UIApplicationDidReceiveMemoryWarningNotification.

let notification = Notification<Any?, AnyObject>(name: "MyEventNotification")

let observer = NotificationObserver(notification) { (value, sender) in
    // handle notification
    // value is nil, sender is nil
}

// notification value is `Any?`, so pass nil
notification.post(nil)

Working with traditional Cocoa notifications

The library can also handle traditional notifications that are posted by the OS. Instead of using the (value, sender) handler, use the (notification) handler which passes the full NSNotification object.

let notification = CocoaNotification(name: UIApplicationDidReceiveMemoryWarningNotification)

let observer = CocoaObserver(notification, handler: { (notification: NSNotification) in
    // handle the notification
})

// the notification will be posted by iOS

Unit tests

There’s a suite of unit tests for the JSQNotificationObserverKit.framework. To run them, open JSQNotificationObserverKit.xcodeproj, select the JSQNotificationObserverKit scheme, then ⌘-u.

These tests are well commented and serve as further documentation for how to use this library.

Contribute

Please follow these sweet contribution guidelines.

Credits

Created and maintained by @jesse_squires.

License

JSQNotificationObserverKit is released under an MIT License. See LICENSE for details.

Copyright © 2014-present Jesse Squires.

Please provide attribution, it is greatly appreciated.