KVNProgress is a fully customizable progress HUD that can be full screen or not.
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
- Preview
- Advantages
- Demo
- Installation
- Usage
- Basics
- [Progress] (#progress)
- Indeterminate progress
- Determinate progress
- [Stop button] (#stop-button)
- Dismiss
- Success/Error
- Customization
- [Known bugs] (#known-bugs)
- Remains to do
- License
- Credits
Base interface:
Full screen interface:
Example of customized interface:
- 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
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.
CocoaPods recommended to use KVNProgress.
- Add
pod 'KVNProgress'
to your Podfile. - Install the pod(s) by running
pod install
. - Include KVNProgress wherever you need it with
#import <KVNProgress/KVNProgress.h>
.
- Download the latest code version or add the repository as a git submodule to your git-tracked project.
- 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.
- Include KVNProgress wherever you need it with
#import <KVNProgress/KVNProgress.h>
.
Check out the provided demo app for many examples how you can use the components.
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>
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"];
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];
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];
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.
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:
.
The appearance of KVNProgress is very customizable. If something is missing or could be added, don't hesitate to ask for it!
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.
You can enable haptic feedback for errors and successes by doing:
KVNProgressConfiguration *configuration = [[KVNProgressConfiguration alloc] init];
if (@available(iOS 10, *)) {
configuration.enableUIFeedback = YES;
}
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 of0.3
seconds. It handles all HUD's except for success and error ones.minimumSuccessDisplayTime
that has a default value of2.0
seconds. It handles all success HUD's.minimumErrorDisplayTime
that has a default value of1.3
seconds. It handles all error HUD's.
- 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 onalertView:didDismissWithButtonIndex:
to be sure theUIAlertView
is completely dismissed before showing an HUD.
- Use real-time blur
- Xcode 6
- iOS 7
- ARC
- Frameworks:
- QuartzCore
- GLKit
This project is under MIT license. For more information, see LICENSE
file.
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! :)