Inherits from UIView
Declared in MBProgressHUD.h
MBProgressHUD.m

Overview

Displays a simple HUD window containing a progress indicator and two optional labels for short messages.

This is a simple drop-in class for displaying a progress HUD view similar to Apples private UIProgressHUD class. The MBProgressHUD window spans over the entire space given to it by the initWithFrame constructor and catches all user input on this region, thereby preventing the user operations on components below the view. The HUD itself is drawn centered as a rounded semi-transparent view witch resizes depending on the user specified content.

This view supports three modes of operation:

  • MBProgressHUDModeIndeterminate – shows a UIActivityIndicatorView
  • MBProgressHUDModeDeterminate – shows a custom round progress indicator (MBRoundProgressView)
  • MBProgressHUDModeCustomView – shows an arbitrary, user specified view (@see customView)

All three modes can have optional labels assigned:

  • If the labelText property is set and non-empty then a label containing the provided content is placed below the indicator view.
  • If also the detailsLabelText property is set then another label is placed below the first label.

License: Copyright © 2011 Matej Bukovinski. This code is distributed under the terms and conditions of the MIT license.

Tasks

  • + showHUDAddedTo:animated:

    Creates a new HUD, adds it to provided view and shows it. The counterpart to this method is hideHUDForView:animated:.
  • + hideHUDForView:animated:

    Finds a HUD sibview and hides it. The counterpart to this method is showHUDAddedTo:animated:.
  • – initWithWindow:

    A convenience constructor that initializes the HUD with the window’s bounds. Calls the designated constructor with window.bounds as the parameter.
  • – initWithView:

    A convenience constructor that initializes the HUD with the view’s bounds. Calls the designated constructor with view.bounds as the parameter
  •   customView

    The UIView (i.g., a UIIMageView) to be shown when the HUD is in MBProgressHUDModeCustomView. For best results use a 37 by 37 pixel view (so the bounds match the build in indicator bounds).

         property
  •   mode

    MBProgressHUD operation mode. Switches between indeterminate (MBProgressHUDModeIndeterminate) and determinate progress (MBProgressHUDModeDeterminate). The default is MBProgressHUDModeIndeterminate.

         property
  •   animationType

    The animation type that should be used when the HUD is shown and hidden.

         property
  •   delegate

    The HUD delegate object. If set the delegate will receive hudWasHidden callbacks when the HUD was hidden. The delegate should conform to the MBProgressHUDDelegate protocol and implement the hudWasHidden method. The delegate object will not be retained.

         property
  •   labelText

    An optional short message to be displayed below the activity indicator. The HUD is automatically resized to fit the entire text. If the text is too long it will get clipped by displaying “…” at the end. If left unchanged or set to @“”, then no message is displayed.

         property
  •   detailsLabelText

    An optional details message displayed below the labelText message. This message is displayed only if the labelText property is also set and is different from an empty string (@“”).

         property
  •   opacity

    The opacity of the HUD window. Defaults to 0.9 (90% opacity).

         property
  •   xOffset

    The x-axis offset of the HUD relative to the centre of the superview.

         property
  •   yOffset

    The y-ayis offset of the HUD relative to the centre of the superview.

         property
  •   margin

    The amounth of space between the HUD edge and the HUD elements (labels, indicators or custom views).

         property
  •   dimBackground

    Cover the HUD background view with a radial gradient.

         property
  •   minShowTime

    The minimum time (in seconds) that the HUD is shown. This avoids the problem of the HUD being shown and than instantly hidden. Defaults to 0 (no minimum show time).

         property
  •   taskInProgress

    Indicates that the executed operation is in progress. Needed for correct graceTime operation. If you don’t set a graceTime (different than 0.0) this does nothing. This property is automatically set when using showWhileExecuting:onTarget:withObject:animated:. When threading is done outside of the HUD (i.e., when the show: and hide: methods are used directly), you need to set this property when your task starts and completes in order to have normal graceTime functunality.

         property
  •   removeFromSuperViewOnHide

    Removes the HUD from it’s parent view when hidden. Defaults to NO.

         property
  •   labelFont

    Font to be used for the main label. Set this property if the default is not adequate.

         property
  •   detailsLabelFont

    Font to be used for the details label. Set this property if the default is not adequate.

         property
  •   progress

    The progress of the progress indicator, from 0.0 to 1.0. Defaults to 0.0.

         property
  • – show:

    Display the HUD. You need to make sure that the main thread completes its run loop soon after this method call so the user interface can be updated. Call this method when your task is already set-up to be executed in a new thread (e.g., when using something like NSOperation or calling an asynchronous call like NSUrlRequest).
  • – hide:

    Hide the HUD. This still calls the hudWasHidden delegate. This is the counterpart of the hide: method. Use it to hide the HUD when your task completes.
  • – hide:afterDelay:

    Hide the HUD after a delay. This still calls the hudWasHidden delegate. This is the counterpart of the hide: method. Use it to hide the HUD when your task completes.
  • – showWhileExecuting:onTarget:withObject:animated:

    Shows the HUD while a background task is executing in a new thread, then hides the HUD.

Properties

animationType

The animation type that should be used when the HUD is shown and hidden.

@property (assign) MBProgressHUDAnimation animationType

Discussion

The animation type that should be used when the HUD is shown and hidden.

Declared In

MBProgressHUD.h

customView

The UIView (i.g., a UIIMageView) to be shown when the HUD is in MBProgressHUDModeCustomView. For best results use a 37 by 37 pixel view (so the bounds match the build in indicator bounds).

@property (retain) UIView *customView

Discussion

The UIView (i.g., a UIIMageView) to be shown when the HUD is in MBProgressHUDModeCustomView. For best results use a 37 by 37 pixel view (so the bounds match the build in indicator bounds).

Declared In

MBProgressHUD.h

delegate

The HUD delegate object. If set the delegate will receive hudWasHidden callbacks when the HUD was hidden. The delegate should conform to the MBProgressHUDDelegate protocol and implement the hudWasHidden method. The delegate object will not be retained.

@property (assign) id<MBProgressHUDDelegate> delegate

Discussion

The HUD delegate object. If set the delegate will receive hudWasHidden callbacks when the HUD was hidden. The delegate should conform to the MBProgressHUDDelegate protocol and implement the hudWasHidden method. The delegate object will not be retained.

Declared In

MBProgressHUD.h

detailsLabelFont

Font to be used for the details label. Set this property if the default is not adequate.

@property (retain) UIFont *detailsLabelFont

Discussion

Font to be used for the details label. Set this property if the default is not adequate.

Declared In

MBProgressHUD.h

detailsLabelText

An optional details message displayed below the labelText message. This message is displayed only if the labelText property is also set and is different from an empty string (@“”).

@property (copy) NSString *detailsLabelText

Discussion

An optional details message displayed below the labelText message. This message is displayed only if the labelText property is also set and is different from an empty string (@“”).

Declared In

MBProgressHUD.h

dimBackground

Cover the HUD background view with a radial gradient.

@property (assign) BOOL dimBackground

Discussion

Cover the HUD background view with a radial gradient.

Declared In

MBProgressHUD.h

labelFont

Font to be used for the main label. Set this property if the default is not adequate.

@property (retain) UIFont *labelFont

Discussion

Font to be used for the main label. Set this property if the default is not adequate.

Declared In

MBProgressHUD.h

labelText

An optional short message to be displayed below the activity indicator. The HUD is automatically resized to fit the entire text. If the text is too long it will get clipped by displaying “…” at the end. If left unchanged or set to @“”, then no message is displayed.

@property (copy) NSString *labelText

Discussion

An optional short message to be displayed below the activity indicator. The HUD is automatically resized to fit the entire text. If the text is too long it will get clipped by displaying “…” at the end. If left unchanged or set to @“”, then no message is displayed.

Declared In

MBProgressHUD.h

margin

The amounth of space between the HUD edge and the HUD elements (labels, indicators or custom views).

@property (assign) float margin

Discussion

The amounth of space between the HUD edge and the HUD elements (labels, indicators or custom views).

Defaults to 20.0

Declared In

MBProgressHUD.h

minShowTime

The minimum time (in seconds) that the HUD is shown. This avoids the problem of the HUD being shown and than instantly hidden. Defaults to 0 (no minimum show time).

@property (assign) float minShowTime

Discussion

The minimum time (in seconds) that the HUD is shown. This avoids the problem of the HUD being shown and than instantly hidden. Defaults to 0 (no minimum show time).

Declared In

MBProgressHUD.h

mode

MBProgressHUD operation mode. Switches between indeterminate (MBProgressHUDModeIndeterminate) and determinate progress (MBProgressHUDModeDeterminate). The default is MBProgressHUDModeIndeterminate.

@property (assign) MBProgressHUDMode mode

Discussion

MBProgressHUD operation mode. Switches between indeterminate (MBProgressHUDModeIndeterminate) and determinate progress (MBProgressHUDModeDeterminate). The default is MBProgressHUDModeIndeterminate.

Declared In

MBProgressHUD.h

opacity

The opacity of the HUD window. Defaults to 0.9 (90% opacity).

@property (assign) float opacity

Discussion

The opacity of the HUD window. Defaults to 0.9 (90% opacity).

Declared In

MBProgressHUD.h

progress

The progress of the progress indicator, from 0.0 to 1.0. Defaults to 0.0.

@property (assign) float progress

Discussion

The progress of the progress indicator, from 0.0 to 1.0. Defaults to 0.0.

Declared In

MBProgressHUD.h

removeFromSuperViewOnHide

Removes the HUD from it’s parent view when hidden. Defaults to NO.

@property (assign) BOOL removeFromSuperViewOnHide

Discussion

Removes the HUD from it’s parent view when hidden. Defaults to NO.

Declared In

MBProgressHUD.h

taskInProgress

Indicates that the executed operation is in progress. Needed for correct graceTime operation. If you don’t set a graceTime (different than 0.0) this does nothing. This property is automatically set when using showWhileExecuting:onTarget:withObject:animated:. When threading is done outside of the HUD (i.e., when the show: and hide: methods are used directly), you need to set this property when your task starts and completes in order to have normal graceTime functunality.

@property (assign) BOOL taskInProgress

Discussion

Indicates that the executed operation is in progress. Needed for correct graceTime operation. If you don’t set a graceTime (different than 0.0) this does nothing. This property is automatically set when using showWhileExecuting:onTarget:withObject:animated:. When threading is done outside of the HUD (i.e., when the show: and hide: methods are used directly), you need to set this property when your task starts and completes in order to have normal graceTime functunality.

Declared In

MBProgressHUD.h

xOffset

The x-axis offset of the HUD relative to the centre of the superview.

@property (assign) float xOffset

Discussion

The x-axis offset of the HUD relative to the centre of the superview.

Declared In

MBProgressHUD.h

yOffset

The y-ayis offset of the HUD relative to the centre of the superview.

@property (assign) float yOffset

Discussion

The y-ayis offset of the HUD relative to the centre of the superview.

Declared In

MBProgressHUD.h

Class Methods

hideHUDForView:animated:

Finds a HUD sibview and hides it. The counterpart to this method is showHUDAddedTo:animated:.

+ (BOOL)hideHUDForView:(UIView *)view animated:(BOOL)animated

Parameters

view

The view that is going to be searched for a HUD subview.

animated

If set to YES the HUD will disappear using the current animationType. If set to NO the HUD will not use animations while disappearing.

Return Value

YES if a HUD was found and removed, NO otherwise.

Discussion

Finds a HUD sibview and hides it. The counterpart to this method is showHUDAddedTo:animated:.

See Also

Declared In

MBProgressHUD.h

showHUDAddedTo:animated:

Creates a new HUD, adds it to provided view and shows it. The counterpart to this method is hideHUDForView:animated:.

+ (MBProgressHUD *)showHUDAddedTo:(UIView *)view animated:(BOOL)animated

Parameters

view

The view that the HUD will be added to

animated

If set to YES the HUD will disappear using the current animationType. If set to NO the HUD will not use animations while disappearing.

Return Value

A reference to the created HUD.

Discussion

Creates a new HUD, adds it to provided view and shows it. The counterpart to this method is hideHUDForView:animated:.

See Also

Declared In

MBProgressHUD.h

Instance Methods

hide:

Hide the HUD. This still calls the hudWasHidden delegate. This is the counterpart of the hide: method. Use it to hide the HUD when your task completes.

- (void)hide:(BOOL)animated

Parameters

animated

If set to YES the HUD will disappear using the current animationType. If set to NO the HUD will not use animations while disappearing.

Discussion

Hide the HUD. This still calls the hudWasHidden delegate. This is the counterpart of the hide: method. Use it to hide the HUD when your task completes.

Declared In

MBProgressHUD.h

hide:afterDelay:

Hide the HUD after a delay. This still calls the hudWasHidden delegate. This is the counterpart of the hide: method. Use it to hide the HUD when your task completes.

- (void)hide:(BOOL)animated afterDelay:(NSTimeInterval)delay

Parameters

animated

If set to YES the HUD will disappear using the current animationType. If set to NO the HUD will not use animations while disappearing.

delay

Delay in secons until the HUD is hidden.

Discussion

Hide the HUD after a delay. This still calls the hudWasHidden delegate. This is the counterpart of the hide: method. Use it to hide the HUD when your task completes.

Declared In

MBProgressHUD.h

initWithView:

A convenience constructor that initializes the HUD with the view’s bounds. Calls the designated constructor with view.bounds as the parameter

- (id)initWithView:(UIView *)view

Parameters

view

The view instance that will provide the bounds for the HUD. Should probably be the same instance as the HUD’s superview (i.e., the view that the HUD will be added to).

Discussion

A convenience constructor that initializes the HUD with the view’s bounds. Calls the designated constructor with view.bounds as the parameter

Declared In

MBProgressHUD.h

initWithWindow:

A convenience constructor that initializes the HUD with the window’s bounds. Calls the designated constructor with window.bounds as the parameter.

- (id)initWithWindow:(UIWindow *)window

Parameters

window

The window instance that will provide the bounds for the HUD. Should probably be the same instance as the HUD’s superview (i.e., the window that the HUD will be added to).

Discussion

A convenience constructor that initializes the HUD with the window’s bounds. Calls the designated constructor with window.bounds as the parameter.

Declared In

MBProgressHUD.h

show:

Display the HUD. You need to make sure that the main thread completes its run loop soon after this method call so the user interface can be updated. Call this method when your task is already set-up to be executed in a new thread (e.g., when using something like NSOperation or calling an asynchronous call like NSUrlRequest).

- (void)show:(BOOL)animated

Parameters

animated

If set to YES the HUD will disappear using the current animationType. If set to NO the HUD will not use animations while disappearing.

Discussion

Display the HUD. You need to make sure that the main thread completes its run loop soon after this method call so the user interface can be updated. Call this method when your task is already set-up to be executed in a new thread (e.g., when using something like NSOperation or calling an asynchronous call like NSUrlRequest).

If you need to perform a blocking thask on the main thread, you can try spining the run loop imeidiately after calling this method by using:

[[NSRunLoop currentRunLoop] runUntilDate:[NSDate distantPast]];

Declared In

MBProgressHUD.h

showWhileExecuting:onTarget:withObject:animated:

Shows the HUD while a background task is executing in a new thread, then hides the HUD.

- (void)showWhileExecuting:(SEL)method onTarget:(id)target withObject:(id)object animated:(BOOL)animated

Parameters

method

The method to be executed while the HUD is shown. This method will be executed in a new thread.

target

The object that the target method belongs to.

object

An optional object to be passed to the method.

animated

If set to YES the HUD will disappear using the current animationType. If set to NO the HUD will not use animations while disappearing.

Discussion

Shows the HUD while a background task is executing in a new thread, then hides the HUD.

This method also takes care of NSAutoreleasePools so your method does not have to be concerned with setting up a pool.

Declared In

MBProgressHUD.h