4 // Created by Matej Bukovinski on 2.4.09.
7 // This code is distributed under the terms and conditions of the MIT license.
9 // Copyright © 2009-2016 Matej Bukovinski
11 // Permission is hereby granted, free of charge, to any person obtaining a copy
12 // of this software and associated documentation files (the "Software"), to deal
13 // in the Software without restriction, including without limitation the rights
14 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15 // copies of the Software, and to permit persons to whom the Software is
16 // furnished to do so, subject to the following conditions:
18 // The above copyright notice and this permission notice shall be included in
19 // all copies or substantial portions of the Software.
21 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
29 #import <Foundation/Foundation.h>
30 #import <UIKit/UIKit.h>
31 #import <CoreGraphics/CoreGraphics.h>
33 @class MBBackgroundView;
34 @protocol MBProgressHUDDelegate;
37 extern CGFloat const MBProgressMaxOffset;
39 typedef NS_ENUM(NSInteger, MBProgressHUDMode) {
40 /// UIActivityIndicatorView.
41 MBProgressHUDModeIndeterminate,
42 /// A round, pie-chart like, progress view.
43 MBProgressHUDModeDeterminate,
44 /// Horizontal progress bar.
45 MBProgressHUDModeDeterminateHorizontalBar,
46 /// Ring-shaped progress view.
47 MBProgressHUDModeAnnularDeterminate,
48 /// Shows a custom view.
49 MBProgressHUDModeCustomView,
50 /// Shows only labels.
54 typedef NS_ENUM(NSInteger, MBProgressHUDAnimation) {
56 MBProgressHUDAnimationFade,
57 /// Opacity + scale animation (zoom in when appearing zoom out when disappearing)
58 MBProgressHUDAnimationZoom,
59 /// Opacity + scale animation (zoom out style)
60 MBProgressHUDAnimationZoomOut,
61 /// Opacity + scale animation (zoom in style)
62 MBProgressHUDAnimationZoomIn
65 typedef NS_ENUM(NSInteger, MBProgressHUDBackgroundStyle) {
66 /// Solid color background
67 MBProgressHUDBackgroundStyleSolidColor,
68 /// UIVisualEffectView or UIToolbar.layer background view
69 MBProgressHUDBackgroundStyleBlur
72 typedef void (^MBProgressHUDCompletionBlock)(void);
75 NS_ASSUME_NONNULL_BEGIN
79 * Displays a simple HUD window containing a progress indicator and two optional labels for short messages.
81 * This is a simple drop-in class for displaying a progress HUD view similar to Apple's private UIProgressHUD class.
82 * The MBProgressHUD window spans over the entire space given to it by the initWithFrame: constructor and catches all
83 * user input on this region, thereby preventing the user operations on components below the view.
85 * @note To still allow touches to pass through the HUD, you can set hud.userInteractionEnabled = NO.
86 * @attention MBProgressHUD is a UI class and should therefore only be accessed on the main thread.
88 @interface MBProgressHUD : UIView
91 * Creates a new HUD, adds it to provided view and shows it. The counterpart to this method is hideHUDForView:animated:.
93 * @note This method sets removeFromSuperViewOnHide. The HUD will automatically be removed from the view hierarchy when hidden.
95 * @param view The view that the HUD will be added to
96 * @param animated If set to YES the HUD will appear using the current animationType. If set to NO the HUD will not use
97 * animations while appearing.
98 * @return A reference to the created HUD.
100 * @see hideHUDForView:animated:
103 + (instancetype)showHUDAddedTo:(UIView *)view animated:(BOOL)animated;
105 /// @name Showing and hiding
108 * Finds the top-most HUD subview that hasn't finished and hides it. The counterpart to this method is showHUDAddedTo:animated:.
110 * @note This method sets removeFromSuperViewOnHide. The HUD will automatically be removed from the view hierarchy when hidden.
112 * @param view The view that is going to be searched for a HUD subview.
113 * @param animated If set to YES the HUD will disappear using the current animationType. If set to NO the HUD will not use
114 * animations while disappearing.
115 * @return YES if a HUD was found and removed, NO otherwise.
117 * @see showHUDAddedTo:animated:
120 + (BOOL)hideHUDForView:(UIView *)view animated:(BOOL)animated;
123 * Finds the top-most HUD subview that hasn't finished and returns it.
125 * @param view The view that is going to be searched.
126 * @return A reference to the last HUD subview discovered.
128 + (nullable MBProgressHUD *)HUDForView:(UIView *)view;
131 * A convenience constructor that initializes the HUD with the view's bounds. Calls the designated constructor with
132 * view.bounds as the parameter.
134 * @param view The view instance that will provide the bounds for the HUD. Should be the same instance as
135 * the HUD's superview (i.e., the view that the HUD will be added to).
137 - (instancetype)initWithView:(UIView *)view;
142 * @note You need to make sure that the main thread completes its run loop soon after this method call so that
143 * the user interface can be updated. Call this method when your task is already set up to be executed in a new thread
144 * (e.g., when using something like NSOperation or making an asynchronous call like NSURLRequest).
146 * @param animated If set to YES the HUD will appear using the current animationType. If set to NO the HUD will not use
147 * animations while appearing.
151 - (void)showAnimated:(BOOL)animated;
154 * Hides the HUD. This still calls the hudWasHidden: delegate. This is the counterpart of the show: method. Use it to
155 * hide the HUD when your task completes.
157 * @param animated If set to YES the HUD will disappear using the current animationType. If set to NO the HUD will not use
158 * animations while disappearing.
162 - (void)hideAnimated:(BOOL)animated;
165 * Hides the HUD after a delay. This still calls the hudWasHidden: delegate. This is the counterpart of the show: method. Use it to
166 * hide the HUD when your task completes.
168 * @param animated If set to YES the HUD will disappear using the current animationType. If set to NO the HUD will not use
169 * animations while disappearing.
170 * @param delay Delay in seconds until the HUD is hidden.
174 - (void)hideAnimated:(BOOL)animated afterDelay:(NSTimeInterval)delay;
177 * The HUD delegate object. Receives HUD state notifications.
179 @property (weak, nonatomic) id<MBProgressHUDDelegate> delegate;
182 * Called after the HUD is hiden.
184 @property (copy, nullable) MBProgressHUDCompletionBlock completionBlock;
187 * Grace period is the time (in seconds) that the invoked method may be run without
188 * showing the HUD. If the task finishes before the grace time runs out, the HUD will
189 * not be shown at all.
190 * This may be used to prevent HUD display for very short tasks.
191 * Defaults to 0 (no grace time).
193 @property (assign, nonatomic) NSTimeInterval graceTime;
196 * The minimum time (in seconds) that the HUD is shown.
197 * This avoids the problem of the HUD being shown and than instantly hidden.
198 * Defaults to 0 (no minimum show time).
200 @property (assign, nonatomic) NSTimeInterval minShowTime;
203 * Removes the HUD from its parent view when hidden.
206 @property (assign, nonatomic) BOOL removeFromSuperViewOnHide;
211 * MBProgressHUD operation mode. The default is MBProgressHUDModeIndeterminate.
213 @property (assign, nonatomic) MBProgressHUDMode mode;
216 * A color that gets forwarded to all labels and supported indicators. Also sets the tintColor
217 * for custom views on iOS 7+. Set to nil to manage color individually.
218 * Defaults to semi-translucent black on iOS 7 and later and white on earlier iOS versions.
220 @property (strong, nonatomic, nullable) UIColor *contentColor UI_APPEARANCE_SELECTOR;
223 * The animation type that should be used when the HUD is shown and hidden.
225 @property (assign, nonatomic) MBProgressHUDAnimation animationType UI_APPEARANCE_SELECTOR;
228 * The bezel offset relative to the center of the view. You can use MBProgressMaxOffset
229 * and -MBProgressMaxOffset to move the HUD all the way to the screen edge in each direction.
230 * E.g., CGPointMake(0.f, MBProgressMaxOffset) would position the HUD centered on the bottom edge.
232 @property (assign, nonatomic) CGPoint offset UI_APPEARANCE_SELECTOR;
235 * The amount of space between the HUD edge and the HUD elements (labels, indicators or custom views).
236 * This also represents the minimum bezel distance to the edge of the HUD view.
239 @property (assign, nonatomic) CGFloat margin UI_APPEARANCE_SELECTOR;
242 * The minimum size of the HUD bezel. Defaults to CGSizeZero (no minimum size).
244 @property (assign, nonatomic) CGSize minSize UI_APPEARANCE_SELECTOR;
247 * Force the HUD dimensions to be equal if possible.
249 @property (assign, nonatomic, getter = isSquare) BOOL square UI_APPEARANCE_SELECTOR;
252 * When enabled, the bezel center gets slightly affected by the device accelerometer data.
253 * Has no effect on iOS < 7.0. Defaults to YES.
255 @property (assign, nonatomic, getter=areDefaultMotionEffectsEnabled) BOOL defaultMotionEffectsEnabled UI_APPEARANCE_SELECTOR;
260 * The progress of the progress indicator, from 0.0 to 1.0. Defaults to 0.0.
262 @property (assign, nonatomic) float progress;
264 /// @name ProgressObject
267 * The NSProgress object feeding the progress information to the progress indicator.
269 @property (strong, nonatomic, nullable) NSProgress *progressObject;
274 * The view containing the labels and indicator (or customView).
276 @property (strong, nonatomic, readonly) MBBackgroundView *bezelView;
279 * View covering the entire HUD area, placed behind bezelView.
281 @property (strong, nonatomic, readonly) MBBackgroundView *backgroundView;
284 * The UIView (e.g., a UIImageView) to be shown when the HUD is in MBProgressHUDModeCustomView.
285 * The view should implement intrinsicContentSize for proper sizing. For best results use approximately 37 by 37 pixels.
287 @property (strong, nonatomic, nullable) UIView *customView;
290 * A label that holds an optional short message to be displayed below the activity indicator. The HUD is automatically resized to fit
293 @property (strong, nonatomic, readonly) UILabel *label;
296 * A label that holds an optional details message displayed below the labelText message. The details text can span multiple lines.
298 @property (strong, nonatomic, readonly) UILabel *detailsLabel;
301 * A button that is placed below the labels. Visible only if a target / action is added.
303 @property (strong, nonatomic, readonly) UIButton *button;
308 @protocol MBProgressHUDDelegate <NSObject>
313 * Called after the HUD was fully hidden from the screen.
315 - (void)hudWasHidden:(MBProgressHUD *)hud;
321 * A progress view for showing definite progress by filling up a circle (pie chart).
323 @interface MBRoundProgressView : UIView
326 * Progress (0.0 to 1.0)
328 @property (nonatomic, assign) float progress;
331 * Indicator progress color.
332 * Defaults to white [UIColor whiteColor].
334 @property (nonatomic, strong) UIColor *progressTintColor;
337 * Indicator background (non-progress) color.
338 * Only applicable on iOS versions older than iOS 7.
339 * Defaults to translucent white (alpha 0.1).
341 @property (nonatomic, strong) UIColor *backgroundTintColor;
344 * Display mode - NO = round or YES = annular. Defaults to round.
346 @property (nonatomic, assign, getter = isAnnular) BOOL annular;
352 * A flat bar progress view.
354 @interface MBBarProgressView : UIView
357 * Progress (0.0 to 1.0)
359 @property (nonatomic, assign) float progress;
362 * Bar border line color.
363 * Defaults to white [UIColor whiteColor].
365 @property (nonatomic, strong) UIColor *lineColor;
368 * Bar background color.
369 * Defaults to clear [UIColor clearColor];
371 @property (nonatomic, strong) UIColor *progressRemainingColor;
374 * Bar progress color.
375 * Defaults to white [UIColor whiteColor].
377 @property (nonatomic, strong) UIColor *progressColor;
382 @interface MBBackgroundView : UIView
385 * The background style.
386 * Defaults to MBProgressHUDBackgroundStyleBlur on iOS 7 or later and MBProgressHUDBackgroundStyleSolidColor otherwise.
387 * @note Due to iOS 7 not supporting UIVisualEffectView, the blur effect differs slightly between iOS 7 and later versions.
389 @property (nonatomic) MBProgressHUDBackgroundStyle style;
391 #if __IPHONE_OS_VERSION_MAX_ALLOWED >= 80000 || TARGET_OS_TV
393 * The blur effect style, when using MBProgressHUDBackgroundStyleBlur.
394 * Defaults to UIBlurEffectStyleLight.
396 @property (nonatomic) UIBlurEffectStyle blurEffectStyle;
400 * The background color or the blur tint color.
401 * @note Due to iOS 7 not supporting UIVisualEffectView, the blur effect differs slightly between iOS 7 and later versions.
403 @property (nonatomic, strong) UIColor *color;
407 @interface MBProgressHUD (Deprecated)
409 + (NSArray *)allHUDsForView:(UIView *)view __attribute__((deprecated("Store references when using more than one HUD per view.")));
410 + (NSUInteger)hideAllHUDsForView:(UIView *)view animated:(BOOL)animated __attribute__((deprecated("Store references when using more than one HUD per view.")));
412 - (id)initWithWindow:(UIWindow *)window __attribute__((deprecated("Use initWithView: instead.")));
414 - (void)show:(BOOL)animated __attribute__((deprecated("Use showAnimated: instead.")));
415 - (void)hide:(BOOL)animated __attribute__((deprecated("Use hideAnimated: instead.")));
416 - (void)hide:(BOOL)animated afterDelay:(NSTimeInterval)delay __attribute__((deprecated("Use hideAnimated:afterDelay: instead.")));
418 - (void)showWhileExecuting:(SEL)method onTarget:(id)target withObject:(id)object animated:(BOOL)animated __attribute__((deprecated("Use GCD directly.")));
419 - (void)showAnimated:(BOOL)animated whileExecutingBlock:(dispatch_block_t)block __attribute__((deprecated("Use GCD directly.")));
420 - (void)showAnimated:(BOOL)animated whileExecutingBlock:(dispatch_block_t)block completionBlock:(nullable MBProgressHUDCompletionBlock)completion __attribute__((deprecated("Use GCD directly.")));
421 - (void)showAnimated:(BOOL)animated whileExecutingBlock:(dispatch_block_t)block onQueue:(dispatch_queue_t)queue __attribute__((deprecated("Use GCD directly.")));
422 - (void)showAnimated:(BOOL)animated whileExecutingBlock:(dispatch_block_t)block onQueue:(dispatch_queue_t)queue
423 completionBlock:(nullable MBProgressHUDCompletionBlock)completion __attribute__((deprecated("Use GCD directly.")));
424 @property (assign) BOOL taskInProgress __attribute__((deprecated("No longer needed.")));
426 @property (nonatomic, copy) NSString *labelText __attribute__((deprecated("Use label.text instead.")));
427 @property (nonatomic, strong) UIFont *labelFont __attribute__((deprecated("Use label.font instead.")));
428 @property (nonatomic, strong) UIColor *labelColor __attribute__((deprecated("Use label.textColor instead.")));
429 @property (nonatomic, copy) NSString *detailsLabelText __attribute__((deprecated("Use detailsLabel.text instead.")));
430 @property (nonatomic, strong) UIFont *detailsLabelFont __attribute__((deprecated("Use detailsLabel.font instead.")));
431 @property (nonatomic, strong) UIColor *detailsLabelColor __attribute__((deprecated("Use detailsLabel.textColor instead.")));
432 @property (assign, nonatomic) CGFloat opacity __attribute__((deprecated("Customize bezelView properties instead.")));
433 @property (strong, nonatomic) UIColor *color __attribute__((deprecated("Customize the bezelView color instead.")));
434 @property (assign, nonatomic) CGFloat xOffset __attribute__((deprecated("Set offset.x instead.")));
435 @property (assign, nonatomic) CGFloat yOffset __attribute__((deprecated("Set offset.y instead.")));
436 @property (assign, nonatomic) CGFloat cornerRadius __attribute__((deprecated("Set bezelView.layer.cornerRadius instead.")));
437 @property (assign, nonatomic) BOOL dimBackground __attribute__((deprecated("Customize HUD background properties instead.")));
438 @property (strong, nonatomic) UIColor *activityIndicatorColor __attribute__((deprecated("Use UIAppearance to customize UIActivityIndicatorView. E.g.: [UIActivityIndicatorView appearanceWhenContainedIn:[MBProgressHUD class], nil].color = [UIColor redColor];")));
439 @property (atomic, assign, readonly) CGSize size __attribute__((deprecated("Get the bezelView.frame.size instead.")));
443 NS_ASSUME_NONNULL_END