SwiftMessages

SwiftMessages is an iOS library for displaying brief messages in the form of a status bar across the top or bottom of the screen.

In addition to providing numerous layouts, themes and configuration options, SwiftMessages allows you to fully customize the view:

Copy one of the included nib files into your project and change it.
Subclass MessageView and add elements, etc.
Or just supply an arbitrary instance of UIView.

Try exploring the demo app to get a feel for the extensive configurability of SwiftMessages.

Installation

CocoaPods

Add the following line to your Podfile:

pod 'SwiftMessages'

Carthage

Add the following line to your Cartfile:

github "SwiftKickMobile/SwiftMessages"

Usage

Basics

SwiftMessages.show(view: myView)

Although you can show any instance of UIView, SwiftMessages provides a MessageView class and assortment of nib-based layouts that should handle most cases:

// Instantiate a message view from the provided card view layout. SwiftMessages searches for nib
// files in the main bundle first, so you can easily copy them into your project and make changes.
let view = MessageView.viewFromNib(layout: .CardView)

// Theme message elements with the warning style.
view.configureTheme(.Warning)

// Add a drop shadow.
view.configureDropShadow()

// Set message title, body, and icon. Here, we're overriding the default warning
// image with an emoji character.
view.configureContent(title: "Warning", body: "Consider yourself warned.", iconText: "🤔")

// Show the message.
SwiftMessages.show(view: view)

You may wish to use the view provider variant show(viewProvider:) to ensure that your UIKit code is executed on the main queue:

SwiftMessages.show {
    let view = MessageView.viewFromNib(layout: .CardView)
    // ... configure the view
    return view
}

The SwiftMessages.Config struct provides numerous configuration options that can be passed to show():

var config = SwiftMessages.Config()

// Slide up from the bottom.
config.presentationStyle = .Bottom

// Display in a window at the specified window level: UIWindowLevelStatusBar
// displays over the status bar while UIWindowLevelNormal displays under.
config.presentationContext = .Window(windowLevel: UIWindowLevelStatusBar)

// Disable the default auto-hiding behavior.
config.duration = .Forever

// Dim the background like a popover view. Hide when the background is tapped.
config.dimMode = .Gray(interactive: true)

// Disable the interactive pan-to-hide gesture.
config.interactiveHide = false

// Specify a status bar style to if the message is displayed directly under the status bar.
config.preferredStatusBarStyle = .LightContent

SwiftMessages.show(config: config, view: view)

Customization

MessageView provides the following UI elements, exposed as public, optional @IBOutlets:

Title (UILabel)
Message body (UILabel)
Image Icon (UIImageView)
Text Icon (UILabel)
Button (UIButton)

Because they are optional, you can freely omit the ones you don't need.

The easiest way to customize MessageView is to drag-and-drop one of the pre-defined nib files into your project and make changes. SwiftMessages always searches the main bundle for nib files first, so it is not necessary to rename the file or make a different API call. However, there are some OS-specific considerations to be aware of:

iOS 9+ When using one of the UIStackView layouts, MessageView.nib or CardView.nib, as a starting point, you can simply delete elements from the nib file or hide them — no need to adjust the Auto Layout constraints.
iOS 8 When using MessageViewIOS8.nib, you'll delete the unwanted elements and fix up the Auto Layout constraints. Or just create your own nib from scratch, which is much like creating a custom UITableViewCell or UICollectionViewCell — set the base view's class to MessageView or whatever subclass or view class you're using and wire up the outlets.

To facilitate the use of nib-based layouts, MessageView provides some type-safe convenience methods for loading the pre-defined nibs. In addition, the SwiftMessages class provides some generic loading methods:

// Instantiate MessageView from one of the provided nibs in a type-safe way.
// SwiftMessages searches the main bundle first, so you easily copy the nib into
// your project and modify it while still using this type-safe call.
let view = MessageView.viewFromNib(layout: .CardView)

// Instantiate MessageView from a named nib.
let view: MessageView = try! SwiftMessages.viewFromNib(named: "MyCustomNib")

// Instantiate MyCustomView from a nib named MyCustomView.nib.
let view: MyCustomView = try! SwiftMessages.viewFromNib()

MessageView provides an optional block-based tap handler for the button and another for the view itself:

// Hide when button tapped
messageView.buttonTapHandler = { _ in SwiftMessages.hide() }

// Hide when message view tapped
messageView.tapHandler = { _ in SwiftMessages.hide() }

Message Queueing

You can call SwiftMessages.show() as many times as you like. SwiftMessages maintains a queue shows messages in order, one at a time. If your view implements the Identifiable protocol (as MessageView does), duplicate messages are removed. The pause between messages can be adjusted:

SwiftMessages.pauseBetweenMessages = 1.0

There are a few ways to hide messages programatically:

// Hide the current message.
SwiftMessages.hide()

// Or hide the current message and clear the queue.
SwiftMessages.hideAll()

// Or for a view that implements `Identifiable`:
SwiftMessages.hide(id: someId)

Multiple instances of SwiftMessages can be used to show more than one message at a time. Note that the static SwiftMessages.show() and other static APIs on SwiftMessage are just convenience wrappers around the shared instance SwiftMessages.sharedInstance):

let otherMessages = SwiftMessages()
SwiftMessages.show(...)
otherMessages.show(...)

License

SwiftMessages is distributed under the MIT license. See LICENSE for details.

heyz-lzj/SwiftMessages