Home

Awesome

XestiMonitors

Swift 4.x License Platform

Build Status Code Coverage Documented

CocoaPods Carthage Swift Package Manager

<a name="overview">Overview</a>

The XestiMonitors framework provides more than sixty fully-functional monitor classes right out of the box that make it easy for your app to detect and respond to many common system-generated events.

Among other things, you can think of XestiMonitors as a better way to manage the most common notifications (primarily on iOS and tvOS). At present, XestiMonitors provides “wrappers” around nearly all UIKit notifications (see UIKit Monitors) and many Foundation notifications (see Foundation Monitors).

XestiMonitors also provides convenient “wrappers” around several frameworks and programming interfaces to make them easier for your app to use:

Additional monitors targeting more parts of all four platforms will be rolled out in future releases of XestiMonitors!

Finally, XestiMonitors is extensible—you can easily create your own custom monitors. See Custom Monitors for details.

<a name="reference_documentation">Reference Documentation</a>

Full reference documentation is available courtesy of Jazzy.

<a name="requirements">Requirements</a>

<a name="installation">Installation</a>

<a name="cocoapods_installation">CocoaPods</a>

CocoaPods is a dependency manager for Cocoa projects. You can install it with the following command:

$ gem install cocoapods

To integrate XestiMonitors into your Xcode project using CocoaPods, specify it in your Podfile:

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '9.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'XestiMonitors'
end

Then, run the following command:

$ pod install

<a name="carthage_installation">Carthage</a>

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.

You can install Carthage with Homebrew using the following commands:

$ brew update
$ brew install carthage

To integrate XestiMonitors into your Xcode project using Carthage, specify it in your Cartfile:

github "eBardX/XestiMonitors"

Then, run the following command:

$ carthage update

Finally, drag the built XestiMonitors.framework into your Xcode project.

<a name="spm_installation">Swift Package Manager</a>

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler. It is in early development, but XestiMonitors does support its use on supported platforms.

Once you have your Swift package set up, adding XestiMonitors as a dependency is as easy as adding it to the dependencies value of your Package.swift.

dependencies: [
    .Package(url: "https://github.com/eBardX/XestiMonitors.git")
]

<a name="usage">Usage</a>

All monitor classes conform to the Monitor protocol, thus enabling you to create arrays of monitors that can be started or stopped uniformly—fewer lines of code!

For example, in a view controller, you can lazily instantiate several monitors and, in addition, lazily instantiate an array variable containing these monitors:

import XestiMonitors

lazy var keyboardMonitor = KeyboardMonitor { [unowned self] in
    // do something…
}
lazy var memoryMonitor = MemoryMonitor { [unowned self] in
    // do something…
}
lazy var orientationMonitor = OrientationMonitor { [unowned self] in
    // do something…
}
lazy var monitors: [Monitor] = [keyboardMonitor,
                                memoryMonitor,
                                orientationMonitor]

Then, in the viewWillAppear(_:) and viewWillDisappear(_:) methods, you can simply start or stop all these monitors with a single line of code:

override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)
    monitors.forEach { $0.startMonitoring() }
}

override func viewWillDisappear(_ animated: Bool) {
    monitors.forEach { $0.stopMonitoring() }
    super.viewWillDisappear(animated)
}

Easy peasy!

<a name="core_location_monitors">Core Location Monitors</a>

XestiMonitors provides seven monitor classes wrapping the Core Location framework that you can use to determine the device’s geographic location, altitude, or orientation; or its position relative to a nearby iBeacon:

<a name="core_motion_monitors">Core Motion Monitors</a>

XestiMonitors provides seven monitor classes wrapping the Core Motion framework that you can use to obtain raw and processed motion measurements from the device:

<a name="foundation_monitors">Foundation Monitors</a>

XestiMonitors provides seventeen monitors wrapping Foundation notifications:

<a name="uikit_monitors">UIKit Monitors</a>

XestiMonitors provides numerous monitors wrapping UIKit notifications.

<a name="accessibility_monitors">Accessibility Monitors</a>

XestiMonitors provides three monitor classes that you can use to observe accessibility events generated by the system:

<a name="application_monitors">Application Monitors </a>

XestiMonitors provides seven monitor classes that you can use to observe common events generated by the system about the app:

<a name="device_monitors">Device Monitors</a>

XestiMonitors provides three monitor classes that you can use to detect changes in the characteristics of the device:

<a name="screen_monitors">Screen Monitors</a>

XestiMonitors provides four monitor classes that you can use to detect changes in the properties associated with a screen:

<a name="text_monitors">Text Monitors</a>

XestiMonitors provides four monitor classes that you can use to detect changes in text input mode and content:

<a name="other_uikit_monitors">Other UIKit Monitors</a>

In addition, XestiMonitors provides nine other UIKit monitors:

KeyboardMonitor is especially handy in removing lots of boilerplate code from your app. This is how keyboard monitoring is typically handled in a custom view controller:

func keyboardWillHide(_ notification: Notification) {
    let userInfo = notification.userInfo
    var animationDuration: TimeInterval = 0
    if let value = (userInfo?[UIKeyboardAnimationDurationUserInfoKey] as? NSNumber)?.doubleValue {
        animationDuration = value
    }
    constraint.constant = 0
    UIView.animate(withDuration: animationDuration) {
        self.view.layoutIfNeeded()
    }
}

func keyboardWillShow(_ notification: Notification) {
    let userInfo = notification.userInfo
    var animationDuration: TimeInterval = 0
    if let value = (userInfo?[UIKeyboardAnimationDurationUserInfoKey] as? NSNumber)?.doubleValue {
        animationDuration = value
    }
    var frameEnd = CGRect.zero
    if let value = (userInfo?[UIKeyboardFrameEndUserInfoKey] as? NSValue)?.cgRectValue {
        frameEnd = value
    }
    constraint.constant = frameEnd.height
    UIView.animate(withDuration: animationDuration) {
        self.view.layoutIfNeeded()
    }
}

override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)
    let nc = NotificationCenter.`default`
    nc.addObserver(self, selector: #selector(keyboardWillHide(_:)),
                   name: .UIKeyboardWillHide, object: nil)
    nc.addObserver(self, selector: #selector(keyboardWillShow(_:)),
                   name: .UIKeyboardWillShow, object: nil)
}

override func viewWillDisappear(_ animated: Bool) {
    NotificationCenter.`default`.removeObserver(self)
    super.viewWillDisappear(animated)
}

And this is the XestiMonitors way using KeyboardMonitor:

import XestiMonitors

lazy var keyboardMonitor = KeyboardMonitor { [unowned self] event in
    guard let constraint = self?.constraint,
          let view = self?.view else { return }
    switch event {
    case let .willHide(info):
        constraint.constant = 0
        UIView.animate(withDuration: info.animationDuration) {
            view.layoutIfNeeded()
        }
    case let .willShow(info):
        constraint.constant = info.frameEnd.height
        UIView.animate(withDuration: info.animationDuration) {
            view.layoutIfNeeded()
        }
    default:
        break
    }
}

override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)
    keyboardMonitor.startMonitoring()
}

override func viewWillDisappear(_ animated: Bool) {
    keyboardMonitor.stopMonitoring()
    super.viewWillDisappear(animated)
}

What’s in your wallet?

<a name="other_monitors">Other Monitors</a>

In addition, XestiMonitors provides two other monitors:

<a name="custom_monitors">Custom Monitors</a>

Best of all, the XestiMonitors framework provides several ways to create your own custom monitors quite easily.

Implementing the Monitor Protocol

You can create a new class, or extend an existing class, that conforms to the Monitor protocol. You need only implement the startMonitoring() and stopMonitoring() methods, as well as the isMonitoring property:

import XestiMonitors

extension MegaHoobieWatcher: Monitor {
    var isMonitoring: Bool { return watchingForHoobiesCount() > 0 }

    func startMonitoring() -> Bool {
        guard !isMonitoring else { return }
        beginWatchingForHoobies()
    }

    func stopMonitoring() -> Bool {
        guard isMonitoring else { return }
        endWatchingForHoobies()
    }
}

Note: The guard statements in both startMonitoring() and stopMonitoring() protect against starting or stopping the monitor if it is in the incorrect state. This is considered good coding practice.

Subclassing the BaseMonitor Class

Typically, you will want to create a subclass of BaseMonitor. The advantage of using this abstract base class is that the basic guard logic is taken care of for you. Specifically, the startMonitoring() method does not attempt to start the monitor if it is already active, and the stopMonitoring() method does not attempt to stop the monitor if it is not active. Instead of directly implementing the required protocol methods and properties, you need only override the configureMonitor() and cleanupMonitor() methods of this base class. In fact, you will not be able to override the startMonitoring() and stopMonitoring() methods or the isMonitoring property—they are declared final in BaseMonitor.

import XestiMonitors

class GigaHoobieMonitor: BaseMonitor {
    let handler: (Float) -> Void
    @objc let hoobie: GigaHoobie
    private var observation: NSKeyValueObservation?

    init(_ hoobie: GigaHoobie, handler: @escaping (Float) -> Void) {
        self.handler = handler
        self.hoobie = hoobie
    }

    override func configureMonitor() -> Bool {
        super.configureMonitor()
        observation = hoobie.observe(\.nefariousActivityLevel) { [unowned self] hoobie, _ in
            self.handler(hoobie.nefariousActivityLevel) }
    }

    override func cleanupMonitor() -> Bool {
        observation?.invalidate()
        observation = nil
        super.cleanupMonitor()
    }
}

Note: Be sure to invoke the superclass implementations of both configureMonitor() and cleanupMonitor().

Subclassing the BaseNotificationMonitor Class

If your custom monitor determines events by observing notifications, you should consider creating a subclass of BaseNotificationMonitor instead. In most cases you need only override the addNotificationObservers(_:) method. You can also override the removeNotificationObservers(_:) method if you require extra cleanup when the notification observers are removed upon stopping the monitor. Although this base class inherits from BaseMonitor, you will not be able to override the configureMonitor() and cleanupMonitor() methods—they are declared final in BaseNotificationMonitor.

import XestiMonitors

class TeraHoobieMonitor: BaseNotificationMonitor {
    let handler: (Bool) -> Void
    let hoobie: TeraHoobie

    init(hoobie: TeraHoobie, queue: OperationQueue = .main,
         handler: @escaping (Bool) -> Void) {
        self.handler = handler
        self.hoobie = hoobie
        super.init(queue: queue)
    }

    override func addNotificationObservers() -> Bool {
        super.addNotificationObservers()
        observe(.teraHoobieDidChange) { [unowned self] _ in
            self.handler(self.hoobie.value) }
    }
}

Note: Be sure to invoke the superclass implementations of both addNotificationObservers(_:) and removeNotificationObservers(_:) in your overrides.

<a name="credits">Credits</a>

J. G. Pusey (ebardx@gmail.com)

<a name="license">License</a>

XestiMonitors is available under the MIT license.