tvProgress

tvProgress is an easy way of displaying the progress of an ongoing task on tvOS.

tvProgress is inspired by SVProgressHUD. This library is specifically designed for tvOS and fully respects Apple design and interface guidelines regarding tvOS. It is written using Swift 3.0.

Demo

Try tvProgress with the demo project available in this repo.

Installation

Carthage

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.

You can install Carthage with Homebrew using the following command:

$ brew update
$ brew install carthage

To integrate tvProgress into your Xcode project using Carthage, specify it in your Cartfile:

github "sweebi/tvProgress"

Run carthage update to build the framework and drag the built tvProgress.framework (in Carthage/Build/tvOS folder) into your Xcode project (Linked Frameworks and Libraries in Targets).

Manually

• Drag the tvProgress.xcodeproj file into your project.
• Add the tvProgress framework into Embedded Binaries.
• Near Run button, select Manage scheme.
• Select your app scheme.
• Click on Edit.
• Select Build on the left menu.
• Uncheck Find Implicit Dependencies. This will prevent Xcode from compiling library each time you compile your app.

Usage

(see sample Xcode project in /Demo)

tvProgress is created as a singleton (i.e. it doesn't need to be explicitly allocated and instantiated; you directly call tvProgress.method).

tvProgress usage will block the user while loading content. Use it when you need to.

Using tvProgress is very easy. You can use it doing some very simple operations such as :

tvProgress.show()
//add your code here
tvProgress.dismiss()

You can test if tvProgress is visble with the following property :

public var isVisible: Bool { get }

Showing the HUD

You can show the status of indeterminate tasks using this method:

public static func show(_ status: String? = .none, contentView: UIView? = .none, loaderType lt: tvLoaderType? = .none, style: tvProgressStyle? = .none, withBlurView addBlurView: Bool = true, menuButtonDidPress: (() -> Void)? = .none, playButtonDidPress: (() -> Void)? = .none, andWithMarginTextSize marge: CGFloat = 400, completion: (() -> Void)? = .none) -> Void

Each parameter is optional. You can either :

• simply call show() method to display a simple animation
• specify a status to display a text
• specify a contentView to display the loader on a specific UIView
• specify a loader to change the animation using tvLoaderType enum
• specify a style using tvProgressStyle enum
• specify if you want the background Blur View via the addBlurView parameter
• specify a closure to be executed when the user press the Menu button while tvProgress is displayed
• specify a closure to be executed when the user press the Play/Pause button while tvProgress is displayed

Showing a progress animation

static public func showProgress(_ progress: Double = 0, status: String? = .none, contentView: UIView? = .none, progressType pt: tvProgressType? = .none, style: tvProgressStyle? = .none, withBlurView addBlurView: Bool = true, menuButtonDidPress: (() -> Void)? = .none, playButtonDidPress: (() -> Void)? = .none, andWithMarginTextSize marge: CGFloat = 400, completion: (() -> Void)? = .none) -> Void

Each parameter is optional. You can either :

• simply call showProgress() method to display a simple progress animation
• specify the progress value (must be between 0 and 1)
• specify a status to display a text
• specify a contentView to display the loader on a specific UIView
• specify a loader to change the animation using tvProgressType enum
• specify a style using tvProgressStyle enum
• specify if you want the background Blur View via the addBlurView parameter
• specify a closure to be executed when the user press the Menu button while tvProgress is displayed
• specify a closure to be executed when the user press the Play/Pause button while tvProgress is displayed

Dismissing the HUD

The HUD can be dismissed using:

public static func dismiss(delay: Double = 0) -> Void

Delay parameter is optional.

Displaying Success or Error

If your loading success or fails, you can display a message that gives information about what happened to the user.

public static func showSuccessWithStatus(_ status: String? = .none, andSuccessImage successImage: UIImage? = .none, andStyle style: tvProgressStyle? = .none, andAction action: (label: String, closure: ((Void) -> Void))? = .none, menuButtonDidPress: (() -> Void)? = .none, playButtonDidPress: (() -> Void)? = .none, andWithMarginTextSize marge: CGFloat = 400, completion: (() -> Void)? = .none) -> Void
public static func showErrorWithStatus(_ status: String? = .none, andErrorImage errorImage: UIImage? = .none, andStyle style: tvProgressStyle? = .none, andAction action: (label: String, closure: ((Void) -> Void))? = .none, menuButtonDidPress: (() -> Void)? = .none, playButtonDidPress: (() -> Void)? = .none, andWithMarginTextSize marge: CGFloat = 400, completion: (() -> Void)? = .none) -> Void

As it was for showing and dismissing tvProgress, each parameter is optional so that you can fully customize your success or error displaying. Following parameters are specific to success / error display :

• You can specify an image to be displayed instead of the default image
• You can specify an action. This action is a tuple that contains a label and a closure. If you specify an action, the label will be use to generate a button while the closure will be executed when the user presses the button.

If you specify and action, tvProgress won't dismiss. You have to call the dismiss method in your closure. If you don't specify an action, tvProgress will automatically dismiss the same way SVProgressHUD handles it, that means computing a display time considering the message to be displayed length or 5 seconds if no message is present.

Customization

We just saw that customization is available in every tvProgress method call. You also can globally customize tvProgress using the following properties :

public var loaderType: tvLoaderType!
public var progressType: tvProgressType!
public var style: tvProgressStyle!
public var font: UIFont!
public var successImage: UIImage!
public var errorImage: UIImage!
public var minimumDismissDuration: Double!
public var fadeInAnimationDuration: Double!
public var fadeOutAnimationDuration: Double!

Each of these properties has to be called on tvProgress.sharedInstance

tvProgressStyle Enum

tvProgressStyle is an enum that allows you to customize the appearance of tvProgress

public enum tvProgressStyle {
    case dark
    case light
    case custom(mainColor: UIColor, secondaryColor: UIColor, blurStyle: UIBlurEffectStyle)
}

• dark style displays tvProgress on a dark blurStyle background
• light style displays tvProgress on a light blurStyle background
• custom allows you to specify mainColor, secondaryColor and a UIBlurEffectStyle

tvLoaderType Enum

tvLoaderType is an enum that allows you to customize the appearance of the loader when tvProgress is displayed.

public enum tvLoaderType {
    case default()
    case androidStyle()
    case custom(cl: tvLoaderAnimatable.Type)
}

The enum has 3 different cases :

• default case that allows you to display a simple animated circle
• androidStyle case that allows you to display a animated circle which start point is moving
• custom case is here to allow you to add your own animation. You have to pass a parameter that is a class type confirming to tvLoaderAnimatable protocol.

tvProgressType Enum

tvProgressType is an enum that allows you to customize the appearance of the progress animation when tvProgress is displayed.

public enum tvProgressType {
    case flatCircle()
    case custom(cp: tvProgressAnimatable.Type)
}

The enum has 2 different cases :

• flatCircle case that allows you to display a simple animated circle
• custom case is here to allow you to add your own animation. You have to pass a parameter that is a class type confirming to tvProgressAnimatable protocol.

tvLoaderAnimatable Protocol

You can implement your own class to customize the loader appearance. You can refer to the Demo app to see how you can implement your own tvLoaderAnimatable class.

public protocol tvLoaderAnimatable: class {
    init()
    func configureWithStyle(style: tvProgressStyle) -> (view: UIView, completion: () -> Void)
}

configureWithStyle method is the main method you have to implement. This is where you are going to create a view that is animated. You have to return a tuple that contains the view and a closure. The closure will allow us to remove animations when we dismiss tvProgress.

tvProgressAnimatable Protocol

You can implement your own class to customize the progress animation appearance. You can refer to the Demo app to see how you can implement your own tvProgressAnimatable class.

public protocol tvProgressAnimatable: tvLoaderAnimatable {
    func updateProgress(progress: Double) -> Void
}

updateProgress method is called when a progress animation is already show with the tvProgress.showProgress method. You can update your current progress animation view with the new progress value.

Contributing to this project

If you have feature requests or bug reports, feel free to help out by sending pull requests or by creating new issues.

License

tvProgress is distributed under the terms and conditions of the MIT license. The success and error icons are made by Freepik from Flaticon and are licensed under Creative Commons BY 3.0.

Credits

tvProgress is brought to you by Cédric Eugeni, Antoine Cormery and contributors to the project. If you're using tvProgress in your project, attribution would be very appreciated.