1//
  2//  MBProgressHUD.h
  3//  Version 0.7
  4//  Created by Matej Bukovinski on 2.4.09.
  5//
  6
  7// This code is distributed under the terms and conditions of the MIT license. 
  8
  9// Copyright (c) 2013 Matej Bukovinski
 10//
 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:
 17//
 18// The above copyright notice and this permission notice shall be included in
 19// all copies or substantial portions of the Software.
 20//
 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
 27// THE SOFTWARE.
 28
 29#import <Foundation/Foundation.h>
 30#import <UIKit/UIKit.h>
 31#import <CoreGraphics/CoreGraphics.h>
 32
 33@protocol MBProgressHUDDelegate;
 34
 35
 36typedef enum {
 37	/** Progress is shown using an UIActivityIndicatorView. This is the default. */
 38	MBProgressHUDModeIndeterminate,
 39	/** Progress is shown using a round, pie-chart like, progress view. */
 40	MBProgressHUDModeDeterminate,
 41	/** Progress is shown using a horizontal progress bar */
 42	MBProgressHUDModeDeterminateHorizontalBar,
 43	/** Progress is shown using a ring-shaped progress view. */
 44	MBProgressHUDModeAnnularDeterminate,
 45	/** Shows a custom view */
 46	MBProgressHUDModeCustomView,
 47	/** Shows only labels */
 48	MBProgressHUDModeText
 49} MBProgressHUDMode;
 50
 51typedef enum {
 52	/** Opacity animation */
 53	MBProgressHUDAnimationFade,
 54	/** Opacity + scale animation */
 55	MBProgressHUDAnimationZoom,
 56	MBProgressHUDAnimationZoomOut = MBProgressHUDAnimationZoom,
 57	MBProgressHUDAnimationZoomIn
 58} MBProgressHUDAnimation;
 59
 60
 61#ifndef MB_INSTANCETYPE
 62#if __has_feature(objc_instancetype)
 63	#define MB_INSTANCETYPE instancetype
 64#else
 65	#define MB_INSTANCETYPE id
 66#endif
 67#endif
 68
 69#ifndef MB_STRONG
 70#if __has_feature(objc_arc)
 71	#define MB_STRONG strong
 72#else
 73	#define MB_STRONG retain
 74#endif
 75#endif
 76
 77#ifndef MB_WEAK
 78#if __has_feature(objc_arc_weak)
 79	#define MB_WEAK weak
 80#elif __has_feature(objc_arc)
 81	#define MB_WEAK unsafe_unretained
 82#else
 83	#define MB_WEAK assign
 84#endif
 85#endif
 86
 87#if NS_BLOCKS_AVAILABLE
 88typedef void (^MBProgressHUDCompletionBlock)();
 89#endif
 90
 91
 92/** 
 93 * Displays a simple HUD window containing a progress indicator and two optional labels for short messages.
 94 *
 95 * This is a simple drop-in class for displaying a progress HUD view similar to Apple's private UIProgressHUD class.
 96 * The MBProgressHUD window spans over the entire space given to it by the initWithFrame constructor and catches all
 97 * user input on this region, thereby preventing the user operations on components below the view. The HUD itself is
 98 * drawn centered as a rounded semi-transparent view which resizes depending on the user specified content.
 99 *
100 * This view supports four modes of operation:
101 * - MBProgressHUDModeIndeterminate - shows a UIActivityIndicatorView
102 * - MBProgressHUDModeDeterminate - shows a custom round progress indicator
103 * - MBProgressHUDModeAnnularDeterminate - shows a custom annular progress indicator
104 * - MBProgressHUDModeCustomView - shows an arbitrary, user specified view (@see customView)
105 *
106 * All three modes can have optional labels assigned:
107 * - If the labelText property is set and non-empty then a label containing the provided content is placed below the
108 *   indicator view.
109 * - If also the detailsLabelText property is set then another label is placed below the first label.
110 */
111@interface MBProgressHUD : UIView
112
113/**
114 * Creates a new HUD, adds it to provided view and shows it. The counterpart to this method is hideHUDForView:animated:.
115 * 
116 * @param view The view that the HUD will be added to
117 * @param animated If set to YES the HUD will appear using the current animationType. If set to NO the HUD will not use
118 * animations while appearing.
119 * @return A reference to the created HUD.
120 *
121 * @see hideHUDForView:animated:
122 * @see animationType
123 */
124+ (MB_INSTANCETYPE)showHUDAddedTo:(UIView *)view animated:(BOOL)animated;
125
126/**
127 * Finds the top-most HUD subview and hides it. The counterpart to this method is showHUDAddedTo:animated:.
128 *
129 * @param view The view that is going to be searched for a HUD subview.
130 * @param animated If set to YES the HUD will disappear using the current animationType. If set to NO the HUD will not use
131 * animations while disappearing.
132 * @return YES if a HUD was found and removed, NO otherwise. 
133 *
134 * @see showHUDAddedTo:animated:
135 * @see animationType
136 */
137+ (BOOL)hideHUDForView:(UIView *)view animated:(BOOL)animated;
138
139/**
140 * Finds all the HUD subviews and hides them. 
141 *
142 * @param view The view that is going to be searched for HUD subviews.
143 * @param animated If set to YES the HUDs will disappear using the current animationType. If set to NO the HUDs will not use
144 * animations while disappearing.
145 * @return the number of HUDs found and removed.
146 *
147 * @see hideHUDForView:animated:
148 * @see animationType
149 */
150+ (NSUInteger)hideAllHUDsForView:(UIView *)view animated:(BOOL)animated;
151
152/**
153 * Finds the top-most HUD subview and returns it. 
154 *
155 * @param view The view that is going to be searched.
156 * @return A reference to the last HUD subview discovered.
157 */
158+ (MB_INSTANCETYPE)HUDForView:(UIView *)view;
159
160/**
161 * Finds all HUD subviews and returns them.
162 *
163 * @param view The view that is going to be searched.
164 * @return All found HUD views (array of MBProgressHUD objects).
165 */
166+ (NSArray *)allHUDsForView:(UIView *)view;
167
168/**
169 * A convenience constructor that initializes the HUD with the window's bounds. Calls the designated constructor with
170 * window.bounds as the parameter.
171 *
172 * @param window The window instance that will provide the bounds for the HUD. Should be the same instance as
173 * the HUD's superview (i.e., the window that the HUD will be added to).
174 */
175- (id)initWithWindow:(UIWindow *)window;
176
177/**
178 * A convenience constructor that initializes the HUD with the view's bounds. Calls the designated constructor with
179 * view.bounds as the parameter
180 *
181 * @param view The view instance that will provide the bounds for the HUD. Should be the same instance as
182 * the HUD's superview (i.e., the view that the HUD will be added to).
183 */
184- (id)initWithView:(UIView *)view;
185
186/** 
187 * Display the HUD. You need to make sure that the main thread completes its run loop soon after this method call so
188 * the user interface can be updated. Call this method when your task is already set-up to be executed in a new thread
189 * (e.g., when using something like NSOperation or calling an asynchronous call like NSURLRequest).
190 *
191 * @param animated If set to YES the HUD will appear using the current animationType. If set to NO the HUD will not use
192 * animations while appearing.
193 *
194 * @see animationType
195 */
196- (void)show:(BOOL)animated;
197
198/** 
199 * Hide the HUD. This still calls the hudWasHidden: delegate. This is the counterpart of the show: method. Use it to
200 * hide the HUD when your task completes.
201 *
202 * @param animated If set to YES the HUD will disappear using the current animationType. If set to NO the HUD will not use
203 * animations while disappearing.
204 *
205 * @see animationType
206 */
207- (void)hide:(BOOL)animated;
208
209/** 
210 * Hide the HUD after a delay. This still calls the hudWasHidden: delegate. This is the counterpart of the show: method. Use it to
211 * hide the HUD when your task completes.
212 *
213 * @param animated If set to YES the HUD will disappear using the current animationType. If set to NO the HUD will not use
214 * animations while disappearing.
215 * @param delay Delay in seconds until the HUD is hidden.
216 *
217 * @see animationType
218 */
219- (void)hide:(BOOL)animated afterDelay:(NSTimeInterval)delay;
220
221/** 
222 * Shows the HUD while a background task is executing in a new thread, then hides the HUD.
223 *
224 * This method also takes care of autorelease pools so your method does not have to be concerned with setting up a
225 * pool.
226 *
227 * @param method The method to be executed while the HUD is shown. This method will be executed in a new thread.
228 * @param target The object that the target method belongs to.
229 * @param object An optional object to be passed to the method.
230 * @param animated If set to YES the HUD will (dis)appear using the current animationType. If set to NO the HUD will not use
231 * animations while (dis)appearing.
232 */
233- (void)showWhileExecuting:(SEL)method onTarget:(id)target withObject:(id)object animated:(BOOL)animated;
234
235#if NS_BLOCKS_AVAILABLE
236
237/**
238 * Shows the HUD while a block is executing on a background queue, then hides the HUD.
239 *
240 * @see showAnimated:whileExecutingBlock:onQueue:completionBlock:
241 */
242- (void)showAnimated:(BOOL)animated whileExecutingBlock:(dispatch_block_t)block;
243
244/**
245 * Shows the HUD while a block is executing on a background queue, then hides the HUD.
246 *
247 * @see showAnimated:whileExecutingBlock:onQueue:completionBlock:
248 */
249- (void)showAnimated:(BOOL)animated whileExecutingBlock:(dispatch_block_t)block completionBlock:(MBProgressHUDCompletionBlock)completion;
250
251/**
252 * Shows the HUD while a block is executing on the specified dispatch queue, then hides the HUD.
253 *
254 * @see showAnimated:whileExecutingBlock:onQueue:completionBlock:
255 */
256- (void)showAnimated:(BOOL)animated whileExecutingBlock:(dispatch_block_t)block onQueue:(dispatch_queue_t)queue;
257
258/** 
259 * Shows the HUD while a block is executing on the specified dispatch queue, executes completion block on the main queue, and then hides the HUD.
260 *
261 * @param animated If set to YES the HUD will (dis)appear using the current animationType. If set to NO the HUD will
262 * not use animations while (dis)appearing.
263 * @param block The block to be executed while the HUD is shown.
264 * @param queue The dispatch queue on which the block should be executed.
265 * @param completion The block to be executed on completion.
266 *
267 * @see completionBlock
268 */
269- (void)showAnimated:(BOOL)animated whileExecutingBlock:(dispatch_block_t)block onQueue:(dispatch_queue_t)queue
270		  completionBlock:(MBProgressHUDCompletionBlock)completion;
271
272/**
273 * A block that gets called after the HUD was completely hidden.
274 */
275@property (copy) MBProgressHUDCompletionBlock completionBlock;
276
277#endif
278
279/** 
280 * MBProgressHUD operation mode. The default is MBProgressHUDModeIndeterminate.
281 *
282 * @see MBProgressHUDMode
283 */
284@property (assign) MBProgressHUDMode mode;
285
286/**
287 * The animation type that should be used when the HUD is shown and hidden. 
288 *
289 * @see MBProgressHUDAnimation
290 */
291@property (assign) MBProgressHUDAnimation animationType;
292
293/**
294 * The UIView (e.g., a UIImageView) to be shown when the HUD is in MBProgressHUDModeCustomView.
295 * For best results use a 37 by 37 pixel view (so the bounds match the built in indicator bounds). 
296 */
297@property (MB_STRONG) UIView *customView;
298
299/** 
300 * The HUD delegate object. 
301 *
302 * @see MBProgressHUDDelegate
303 */
304@property (MB_WEAK) id<MBProgressHUDDelegate> delegate;
305
306/** 
307 * An optional short message to be displayed below the activity indicator. The HUD is automatically resized to fit
308 * the entire text. If the text is too long it will get clipped by displaying "..." at the end. If left unchanged or
309 * set to @"", then no message is displayed.
310 */
311@property (copy) NSString *labelText;
312
313/** 
314 * An optional details message displayed below the labelText message. This message is displayed only if the labelText
315 * property is also set and is different from an empty string (@""). The details text can span multiple lines. 
316 */
317@property (copy) NSString *detailsLabelText;
318
319/** 
320 * The opacity of the HUD window. Defaults to 0.8 (80% opacity). 
321 */
322@property (assign) float opacity;
323
324/**
325 * The color of the HUD window. Defaults to black. If this property is set, color is set using
326 * this UIColor and the opacity property is not used.  using retain because performing copy on
327 * UIColor base colors (like [UIColor greenColor]) cause problems with the copyZone.
328 */
329@property (MB_STRONG) UIColor *color;
330
331/** 
332 * The x-axis offset of the HUD relative to the centre of the superview. 
333 */
334@property (assign) float xOffset;
335
336/** 
337 * The y-axis offset of the HUD relative to the centre of the superview. 
338 */
339@property (assign) float yOffset;
340
341/**
342 * The amount of space between the HUD edge and the HUD elements (labels, indicators or custom views). 
343 * Defaults to 20.0
344 */
345@property (assign) float margin;
346
347/** 
348 * Cover the HUD background view with a radial gradient. 
349 */
350@property (assign) BOOL dimBackground;
351
352/*
353 * Grace period is the time (in seconds) that the invoked method may be run without 
354 * showing the HUD. If the task finishes before the grace time runs out, the HUD will
355 * not be shown at all. 
356 * This may be used to prevent HUD display for very short tasks.
357 * Defaults to 0 (no grace time).
358 * Grace time functionality is only supported when the task status is known!
359 * @see taskInProgress
360 */
361@property (assign) float graceTime;
362
363/**
364 * The minimum time (in seconds) that the HUD is shown. 
365 * This avoids the problem of the HUD being shown and than instantly hidden.
366 * Defaults to 0 (no minimum show time).
367 */
368@property (assign) float minShowTime;
369
370/**
371 * Indicates that the executed operation is in progress. Needed for correct graceTime operation.
372 * If you don't set a graceTime (different than 0.0) this does nothing.
373 * This property is automatically set when using showWhileExecuting:onTarget:withObject:animated:.
374 * When threading is done outside of the HUD (i.e., when the show: and hide: methods are used directly),
375 * you need to set this property when your task starts and completes in order to have normal graceTime 
376 * functionality.
377 */
378@property (assign) BOOL taskInProgress;
379
380/**
381 * Removes the HUD from its parent view when hidden. 
382 * Defaults to NO. 
383 */
384@property (assign) BOOL removeFromSuperViewOnHide;
385
386/** 
387 * Font to be used for the main label. Set this property if the default is not adequate. 
388 */
389@property (MB_STRONG) UIFont* labelFont;
390
391/** 
392 * Font to be used for the details label. Set this property if the default is not adequate. 
393 */
394@property (MB_STRONG) UIFont* detailsLabelFont;
395
396/** 
397 * The progress of the progress indicator, from 0.0 to 1.0. Defaults to 0.0. 
398 */
399@property (assign) float progress;
400
401/**
402 * The minimum size of the HUD bezel. Defaults to CGSizeZero (no minimum size).
403 */
404@property (assign) CGSize minSize;
405
406/**
407 * Force the HUD dimensions to be equal if possible. 
408 */
409@property (assign, getter = isSquare) BOOL square;
410
411@end
412
413
414@protocol MBProgressHUDDelegate <NSObject>
415
416@optional
417
418/** 
419 * Called after the HUD was fully hidden from the screen. 
420 */
421- (void)hudWasHidden:(MBProgressHUD *)hud;
422
423@end
424
425
426/**
427 * A progress view for showing definite progress by filling up a circle (pie chart).
428 */
429@interface MBRoundProgressView : UIView 
430
431/**
432 * Progress (0.0 to 1.0)
433 */
434@property (nonatomic, assign) float progress;
435
436/**
437 * Indicator progress color.
438 * Defaults to white [UIColor whiteColor]
439 */
440@property (nonatomic, MB_STRONG) UIColor *progressTintColor;
441
442/**
443 * Indicator background (non-progress) color.
444 * Defaults to translucent white (alpha 0.1)
445 */
446@property (nonatomic, MB_STRONG) UIColor *backgroundTintColor;
447
448/*
449 * Display mode - NO = round or YES = annular. Defaults to round.
450 */
451@property (nonatomic, assign, getter = isAnnular) BOOL annular;
452
453@end
454
455
456/**
457 * A flat bar progress view. 
458 */
459@interface MBBarProgressView : UIView
460
461/**
462 * Progress (0.0 to 1.0)
463 */
464@property (nonatomic, assign) float progress;
465
466/**
467 * Bar border line color.
468 * Defaults to white [UIColor whiteColor].
469 */
470@property (nonatomic, MB_STRONG) UIColor *lineColor;
471
472/**
473 * Bar background color.
474 * Defaults to clear [UIColor clearColor];
475 */
476@property (nonatomic, MB_STRONG) UIColor *progressRemainingColor;
477
478/**
479 * Bar progress color.
480 * Defaults to white [UIColor whiteColor].
481 */
482@property (nonatomic, MB_STRONG) UIColor *progressColor;
483
484@end