Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/facebook/KVOController
Simple, modern, thread-safe key-value observing for iOS and OS X.
https://github.com/facebook/KVOController
Last synced: 3 months ago
JSON representation
Simple, modern, thread-safe key-value observing for iOS and OS X.
- Host: GitHub
- URL: https://github.com/facebook/KVOController
- Owner: facebookarchive
- License: other
- Archived: true
- Created: 2014-02-24T20:25:08.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2020-01-25T04:18:28.000Z (almost 5 years ago)
- Last Synced: 2024-05-22T14:33:40.911Z (6 months ago)
- Language: Objective-C
- Homepage:
- Size: 159 KB
- Stars: 7,346
- Watchers: 225
- Forks: 925
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- Awesome-iOS - KVOController - Simple, modern, thread-safe key-value observing. (Foundation)
README
# [KVOController](https://github.com/facebook/KVOController)
[](https://travis-ci.org/facebook/KVOController)
[](https://codecov.io/github/facebook/KVOController)
[](http://cocoadocs.org/docsets/KVOController)
[](http://cocoadocs.org/docsets/KVOController)
Key-value observing is a particularly useful technique for communicating between layers in a Model-View-Controller application. KVOController builds on Cocoa's time-tested key-value observing implementation. It offers a simple, modern API, that is also thread safe. Benefits include:
- Notification using blocks, custom actions, or NSKeyValueObserving callback.
- No exceptions on observer removal.
- Implicit observer removal on controller dealloc.
- Thread-safety with special guards against observer resurrection – [rdar://15985376](http://openradar.appspot.com/radar?id=5305010728468480).
For more information on KVO, see Apple's [Introduction to Key-Value Observing](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/KeyValueObserving/KeyValueObserving.html).
## Usage
Example apps for iOS and OS X are included with the project. Here is one simple usage pattern:
```objective-c
// create KVO controller with observer
FBKVOController *KVOController = [FBKVOController controllerWithObserver:self];
self.KVOController = KVOController;
// observe clock date property
[self.KVOController observe:clock keyPath:@"date" options:NSKeyValueObservingOptionInitial|NSKeyValueObservingOptionNew block:^(ClockView *clockView, Clock *clock, NSDictionary *change) {
// update clock view with new value
clockView.date = change[NSKeyValueChangeNewKey];
}];
```
While simple, the above example is complete. A clock view creates a KVO controller to observe the clock date property. A block callback is used to handle initial and change notification. Unobservation happens implicitly on controller deallocation, since a strong reference to the `KVOController` is kept.
Note: the observer specified must support weak references. The zeroing weak reference guards against notification of a deallocated observer instance.
#### NSObject Category
For an even easier usage, just `#import ` for an automatic `KVOController` property on all objects.
```objc
[self.KVOController observe:clock keyPath:@"date" options:NSKeyValueObservingOptionInitial|NSKeyValueObservingOptionNew action:@selector(updateClockWithDateChange:)];
```
## Swift
KVOController works great in Swift but there are few requirements:
- Your observer should subclass `NSObject`.
- Properties that you observe must be marked as `dynamic`.
Check the following example:
```Swift
class TasksListViewModel: NSObject {
dynamic var tasksList: [TaskList] = []
}
/// In ViewController.swift
import KVOController
kvoController.observe(viewModel,
keyPath: "listsDidChange",
options: [.new, .initial]) { (viewController, viewModel, change) in
self.taskListsTableView.reloadData()
}
```
## Prerequisites
KVOController takes advantage of recent Objective-C runtime advances, including ARC and weak collections. It requires:
- iOS 6 or later.
- OS X 10.7 or later.
## Installation
To install using [CocoaPods](https://github.com/cocoapods/cocoapods), add the following to your project Podfile:
```ruby
pod 'KVOController'
```
To install using [Carthage](https://github.com/carthage/carthage), add the following to your project Cartfile:
```
github "facebook/KVOController"
```
Alternatively, drag and drop FBKVOController.h and FBKVOController.m into your Xcode project, agreeing to copy files if needed. For iOS applications, you can choose to link against the static library target of the KVOController project.
Having installed using CocoaPods or Carthage, add the following to import in Objective-C:
```objective-c
#import
```
## Testing
The unit tests included use CocoaPods for managing dependencies. Install CocoaPods if you haven't already done so. Then, at the command line, navigate to the root KVOController directory and type:
```sh
pod install
```
This will install and add test dependencies on OCHamcrest and OCMockito. Re-open the Xcode KVOController workspace and Test, ⌘U.
## License
KVOController is released under a BSD License. See LICENSE file for details.