/KVNProgress

KVNProgress is a fully customizable progress HUD that can be full screen or not.

Primary LanguageObjective-CMIT LicenseMIT

KVNProgress

Coverage Status Build Status Twitter: @kevinh6113 License: MIT Version Cocoapods

KVNProgress is a fully customizable progress HUD that can be full screen or not.

Using KVNProgress in your app?

If you're using KVNProgress in your app, I'd love to hear it! 😀
Please, make sure to shout it proudly here 👍
Assisto and 12,021* apps currently using KVNProgress and counting...
* stats via CocoaPods

Table of contents

Preview

Base interface:
Indeterminate progress Determinate progress Success HUD Error HUD
Full screen interface:
Full screen indeterminate progress Full screen determinate progress Full screen success HUD Full screen error HUD
Example of customized interface:

Advantages

  • Can be full screen
  • Uses UIMotionEffect
  • Supports all orientations
  • Supports iPad
  • Animates text update
  • Animates success checkmark
  • Is well documented
  • Is fully customizable
    • Colors
    • Fonts
    • Circle size and thickness
    • Blur or solid color background

Demo

Here is a video of the demo app that you can find in this project. If you want to try it yourself, just download/checkout this repository and launch the project in Xcode.

Demo video

Installation

Cocoapods

CocoaPods recommended to use KVNProgress.

  1. Add pod 'KVNProgress' to your Podfile.
  2. Install the pod(s) by running pod install.
  3. Include KVNProgress wherever you need it with #import <KVNProgress/KVNProgress.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 Classes, Categories and also the Resources 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 KVNProgress wherever you need it with #import <KVNProgress/KVNProgress.h>.

Usage

Check out the provided demo app for many examples how you can use the components.

Basics

KVNProgress HUD will block the user from interacting with the interface behind it. You can customize colors, font and size of the HUD.

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

#import <KVNProgress/KVNProgress.h>

Progress

Indeterminate progress

To show an indeterminate progress:

[KVNProgress show];

// Adds a status below the circle
[KVNProgress showWithStatus:@"Loading"];

// Adds the HUD to a certain view instead of main window
[KVNProgress showWithStatus:@"Loading"
                     onView:view];

To change the status on the fly (animated):

 [KVNProgress updateStatus:@"New status"];

Determinate progress

To show a determinate progress and change its value along time:

// Progress has to be between 0 and 1
[KVNProgress showProgress:0.5f];

// Adds a status below the progress
[KVNProgress showProgress:0.5f
                   status:@"Loading"];

// Adds the HUD to a certain view instead of main window
[KVNProgress showProgress:0.5f
                   status:@"Loading"
                   onView:view];

// Updates the progress
[KVNProgress updateProgress:0.75f
                   animated:YES];

Stop button

You can add a stop button to a progress HUD. For this you will need to use the KVNProgressConfiguration(see below). You simply have to put:

KVNProgressConfiguration *configuration = [KVNProgressConfiguration defaultConfiguration];
configuration.showStop = YES;
configuration.tapBlock = ^(KVNProgress *progressView) {
	// Do what you want
	[KVNProgress dismiss];
};

[KVNProgress setConfiguration:configuration];

tapBlock will be executed when HUD is tapped. If no tapBlock is specified, showStop will not be activated!

You can customize stop button size. Defaults to 30% of the circle size.

configuration.stopRelativeHeight = 0.3f;
configuration.stopColor = [UIColor whiteColor];

Dismiss

To dismiss after your task is done:

// Dismiss
[KVNProgress dismiss];

When necessary, you can use:

// Dismiss
[KVNProgress dismissWithCompletion:^{
   // Things you want to do after the HUD is gone.
}];

Why?

Because KVNProgress remains visible for a certain time even if you call dismiss. This is done to ensure the user has enough time to see the HUD if the dismiss is called too quick after a show. The completion block in dismissWithCompletion is called (on the main thread) after the HUD is completely dismissed. This minimum amount of display time is defined in the KVNProgressConfiguration object (explained below). Default value is 0.3 seconds.

Success/Error

To show a success HUD with a checkmark:

[KVNProgress showSuccess];

// Or
[KVNProgress showSuccessWithStatus:@"Success"];

// Adds the HUD to a certain view instead of main window
[KVNProgress showSuccessWithStatus:@"Success"
                            onView:view];

To show an error HUD with a cross:

[KVNProgress showError];

// Or
[KVNProgress showErrorWithStatus:@"Error"];

// Adds the HUD to a certain view instead of main window
[KVNProgress showErrorWithStatus:@"Error"
                          onView:view];

Dismiss is automatic for successes and errors. If you want to do something after the dismissal, you can use the above methods with the final parameter completion: showSuccessWithCompletion:, showSuccessWithStatus:completion:, showSuccessWithStatus:onView:completion:, showErrorWithCompletion:, showErrorWithStatus:completion:, showErrorWithStatus:onView:completion:.

Customization

The appearance of KVNProgress is very customizable. If something is missing or could be added, don't hesitate to ask for it!

KVNProgressConfiguration

You can setup your HUD UI in your UI setups for your app using the KVNProgressConfiguration. Here is an example on how to simply set the default configuration for you HUD:

[KVNProgress setConfiguration:[KVNProgressConfiguration defaultConfiguration]];

Note that if you just want the default configuration, the above code is not needed. If you do not set a configuration, the default one is taken ;)

Here is an example of a complete custom configuration:

 KVNProgressConfiguration *configuration = [[KVNProgressConfiguration alloc] init];

  configuration.statusColor = [UIColor whiteColor];
  configuration.statusFont = [UIFont fontWithName:@"HelveticaNeue-Thin" size:15.0f];
  configuration.circleStrokeForegroundColor = [UIColor whiteColor];
  configuration.circleStrokeBackgroundColor = [UIColor colorWithWhite:1.0f alpha:0.3f];
  configuration.circleFillBackgroundColor = [UIColor colorWithWhite:1.0f alpha:0.1f];
  configuration.backgroundFillColor = [UIColor colorWithRed:0.173f green:0.263f blue:0.856f alpha:0.9f];
  configuration.backgroundTintColor = [UIColor colorWithRed:0.173f green:0.263f blue:0.856f alpha:1.0f];
  configuration.successColor = [UIColor whiteColor];
  configuration.errorColor = [UIColor whiteColor];
  configuration.stopColor = [UIColor whiteColor];
  configuration.circleSize = 110.0f;
  configuration.lineWidth = 1.0f;
  configuration.fullScreen = NO;
  configuration.showStop = YES;
  configuration.stopRelativeHeight = 0.4f;

configuration.tapBlock = ^(KVNProgress *progressView) {
  // Do something you want to do when the user tap on the HUD
  // Does nothing by default
};

// You can allow user interaction for behind views but you will losse the tapBlock functionnality just above
// Does not work with fullscreen mode
// Default is NO
configuration.allowUserInteraction = NO;

  [KVNProgress setConfiguration:configuration];

If you do not specify certain properties for a configuration, they will automatically be the default's one.

Haptic feedback

You can enable haptic feedback for errors and successes by doing:

KVNProgressConfiguration *configuration = [[KVNProgressConfiguration alloc] init];

if (@available(iOS 10, *)) {
	configuration.enableUIFeedback = YES;
}

Display times

To avoid the user to see a blinking HUD or even don't see it at all if you are dismissing it too quickly, the HUD will stay display for a minimum (short) period of time.

There are 3 properties you can change that do that in KVNProgressConfiguration to do that:

  • minimumDisplayTime that has a default value of 0.3 seconds. It handles all HUD's except for success and error ones.
  • minimumSuccessDisplayTime that has a default value of 2.0 seconds. It handles all success HUD's.
  • minimumErrorDisplayTime that has a default value of 1.3 seconds. It handles all error HUD's.

Known bugs

  • Showing an HUD on alertView:clickedButtonAtIndex: will give an undefined behavior that can sometimes make the HUD not appear (#29 - resolution comment). Instead, call the HUD on alertView:didDismissWithButtonIndex: to be sure the UIAlertView is completely dismissed before showing an HUD.

Remains to do

  • Use real-time blur

Requirements

  • Xcode 6
  • iOS 7
  • ARC
  • Frameworks:
    • QuartzCore
    • GLKit

License

This project is under MIT license. For more information, see LICENSE file.

Credits

KVNProgress was inspired by MRProgress UI.

KVNProgress was done to integrate in a project I work on: Assisto. It will be updated when necessary and fixes will be done as soon as discovered to keep it up to date.

I work at Pinch.

You can find me on Twitter @kevinh6113.

Enjoy! :)