SVProgressHUD is a clean and easy-to-use HUD meant to display the progress of an ongoing task.
I'm not a big fan of CocoaPods, so tend to not keep it updated. If you really want to use SVProgressHUD with CocoaPods, I suggest you use pod 'SVProgressHUD', :head
to pull from the master
branch directly. I'm usually careful about what I push there and is the version I use myself in all my projects.
- Drag the
SVProgressHUD/SVProgressHUD
folder into your project. - Add the QuartzCore framework to your project.
(see sample Xcode project in /Demo
)
SVProgressHUD is created as a singleton (i.e. it doesn't need to be explicitly allocated and instantiated; you directly call [SVProgressHUD method]
).
Use SVProgressHUD wisely! Only use it if you absolutely need to perform a task before taking the user forward. Bad use case examples: pull to refresh, infinite scrolling, sending message.
Using SVProgressHUD in your app will usually look as simple as this (using Grand Central Dispatch):
[SVProgressHUD show];
dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
// time-consuming task
dispatch_async(dispatch_get_main_queue(), ^{
[SVProgressHUD dismiss];
});
});
You can show the status of indeterminate tasks using one of the following:
+ (void)show;
+ (void)showWithMaskType:(SVProgressHUDMaskType)maskType;
+ (void)showWithStatus:(NSString*)string;
+ (void)showWithStatus:(NSString*)string maskType:(SVProgressHUDMaskType)maskType;
If you'd like the HUD to reflect the progress of a task, use one of these:
+ (void)showProgress:(CGFloat)progress;
+ (void)showProgress:(CGFloat)progress status:(NSString*)status;
+ (void)showProgress:(CGFloat)progress status:(NSString*)status maskType:(SVProgressHUDMaskType)maskType;
It can be dismissed right away using:
+ (void)dismiss;
If you'd like to stack HUDs, you can balance out every show call using:
+ (void)popActivity;
The HUD will get dismissed once the popActivity
calls will match the number of show calls.
Or show a confirmation glyph before before getting dismissed a little bit later. The display time depends on the length of the given string (between 0.5 and 5 seconds).
+ (void)showSuccessWithStatus:(NSString*)string;
+ (void)showSuccessWithStatus:(NSString*)string maskType:(SVProgressHUDMaskType)maskType;
+ (void)showErrorWithStatus:(NSString *)string;
+ (void)showErrorWithStatus:(NSString *)string maskType:(SVProgressHUDMaskType)maskType;
+ (void)showImage:(UIImage*)image status:(NSString*)string;
+ (void)showImage:(UIImage*)image status:(NSString*)status maskType:(SVProgressHUDMaskType)maskType;
SVProgressHUD can be customized via the following methods:
+ (void)setBackgroundColor:(UIColor*)color; // default is [UIColor whiteColor]
+ (void)setForegroundColor:(UIColor*)color; // default is [UIColor blackColor]
+ (void)setRingThickness:(CGFloat)width; // default is 4 pt
+ (void)setFont:(UIFont*)font; // default is [UIFont preferredFontForTextStyle:UIFontTextStyleSubheadline]
+ (void)setSuccessImage:(UIImage*)image; // default is bundled success image from Glyphish
+ (void)setErrorImage:(UIImage*)image; // default is bundled error image from Glyphish
SVProgressHUD
posts four notifications via NSNotificationCenter
in response to being shown/dismissed:
SVProgressHUDWillAppearNotification
when the show animation startsSVProgressHUDDidAppearNotification
when the show animation completesSVProgressHUDWillDisappearNotification
when the dismiss animation startsSVProgressHUDDidDisappearNotification
when the dismiss animation completes
Each notification passes a userInfo
dictionary holding the HUD's status string (if any), retrievable via SVProgressHUDStatusUserInfoKey
.
SVProgressHUD
also posts SVProgressHUDDidReceiveTouchEventNotification
when users touch on the overall screen or SVProgressHUDDidTouchDownInsideNotification
when a user touches on the hud directly. For this notifications userInfo
is not passed but the object parameter contains the UIEvent
that related to the touch.
If you have feature requests or bug reports, feel free to help out by sending pull requests or by creating new issues. Please take a moment to review the guidelines written by Nicolas Gallagher:
SVProgressHUD is brought to you by Sam Vermette and contributors to the project. The success and error icons are from Glyphish. If you're using SVProgressHUD in your project, attribution would be nice.