Skip to content

Latest commit

 

History

History
202 lines (129 loc) · 8.03 KB

README.md

File metadata and controls

202 lines (129 loc) · 8.03 KB
Raw

MRProgress

Pod Version Pod Platform

MRProgress is a collection of drop-in components that display a dimmed overlay with a blurred box view with an indicator and/or labels while work is being done in a background thread.

  • Component oriented: You don't have to use all components or MRProgressOverlayView. You can use just the custom activity indicators or progress views.
  • Configurable: All components implement tintColor.
  • Customizable: You can replace the given blur implementation and hook into your own you are maybe already using in other places of your app. Or simply throw in an UIToolbar's layer, if you prefer Apple's implementation. (Current blur implementation is as given by sample code of WWDC 2013.)
  • Reusable: The code is fragmented in small reusable pieces.
  • Well documented: You can install and open Appledoc documentation.

Components

The components used in MRProgressOverlayView could be used seperately. The provided Example app demonstrates how they can be used.

MRProgressOverlayView

  • Supports different modes
  • Animated show and hide
  • Blured background
  • With UIMotionEffects for tilting like UIAlertView
  • Supports multi-line title label text

MRCircularProgressView

  • Tint color can be changed
  • Circular progress view like in AppStore
  • Can display a stop button
  • Animated with CABasicAnimation
  • Percentage label change is animated over a NSTimer

MRNavigationBarProgressView

  • Display a progress view in a UINavigationController
  • Hooks UINavigationControllerDelegate and is automatically removed on push or pop
  • Can be used in UINavigationBar or UIToolbar

MRCheckmarkIconView and MRCrossIconView

  • Tint color can be changed
  • Scalable
  • Animatable
  • Backed by CAShapeLayer

MRActivityIndicatorView

  • Tint color can be changed
  • Same API as UIActivityIndicatorView
  • Can display a stop button
  • Animated with CABasicAnimation

Installation

Cocoapods

CocoaPods is the recommended way to add MRProgress to your project.

  1. Add a pod entry for MRProgress to your Podfile pod 'MRProgress', '~> 0.3'.
  2. Install the pod(s) by running pod install.
  3. Include MRProgress wherever you need it with #import "MRProgress.h".

Source files

  1. Download the latest code version or add the repository as a git submodule to your git-tracked project.
  2. Drag and drop the src directory from the archive in your project navigator. Make sure to select Copy items when asked if you extracted the code archive outside of your project.
  3. Include MRProgress wherever you need any component with #import "MRProgress.h".

Static library

  1. Drag and drop MRProgress.xcodeproj in your project navigator.
  2. Select your target and go to the Build Phases tab. In the Link Binary With Libraries section select the add button. On the sheet find and add libMRProgress.a.
  3. Add Target MRProgress to your Target Dependencies list.
  4. import <MRProgress/MRProgress.h> whereever you want to use the components. You could add it to your Prefix header file, if you want.

Requirements

  • Xcode 5
  • iOS 7
  • ARC
  • Frameworks:
    • QuartzCore
    • CoreGraphics
    • Accelerate

Usage

Check out the provided demo app for many examples how you can use the components. Make sure you also see MRProgress documentation on Cocoadocs.

Basics

  1. Add the following import to the top of the file or to your Prefix header:

    // If used with Cocoapods
#import "MRProgress.h"

    // If used as Framework
#import <MRProgress/MRProgress.h>

  2. Use one the following ways to display the overlay:

    // Block whole window
[MRProgressOverlayView showOverlayAddedTo:self.window animated:YES];

    // Block only the navigation controller
[MRProgressOverlayView showOverlayAddedTo:self.navigationController.view animated:YES];

    // Block only the view
[MRProgressOverlayView showOverlayAddedTo:self.view animated:YES];

    // Block a custom view
[MRProgressOverlayView showOverlayAddedTo:self.imageView animated:YES];

  3. Simply dismiss after complete your task:

    // Dismiss
[MRProgressOverlayView dismissOverlayForView:self.view animated:YES];

Modes

Name (MRProgressOverlayView<...>) Screenshot Description
Indeterminate Progress is shown using a large round activity indicator view. (MRActivityIndicatorView) This is the default.
DeterminateCircular Progress is shown using a round, pie-chart like, progress view. (MRCircularProgressView)
DeterminateHorizontalBar Progress is shown using a horizontal progress bar. (UIProgressView)
IndeterminateSmall Shows primarily a label. Progress is shown using a small activity indicator. (MRActivityIndicatorView)
IndeterminateSmallDefault Shows primarily a label. Progress is shown using a small activity indicator. (UIActivityIndicatorView in UIActivityIndicatorViewStyleGray)
Checkmark Shows a checkmark. (MRCheckmarkIconView)
Cross Shows a cross. (MRCrossIconView)

Credits

MRProgress' API was inspired by MBProgressHUD project.

The acquarium image was stolen by Jag Cesar's blur implementation.

You can find me on Twitter @mrackwitz.

License

Copyright (c) 2013 Marius Rackwitz [email protected]

The MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.