⚠️ Deprecated ⚠️
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
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
CocoaPods (recommended)
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.