noursandid/sundeedspotlight

An easily implemented spotlight library to walk the user through the features

SundeedSpotlight

SundeedSpotlight is an easily implemented spotlight library to walk the user through the features

Requirements

• iOS 9.0+

• XCode 10.3+

• Swift 5+

Installation

---

Installation via CocoaPods

SundeedSpotlight is available through CocoaPods. CocoaPods is a dependency manager that automates and simplifies the process of using 3rd-party libraries like MarkdownKit in your projects. You can install CocoaPods with the following command:

gem install cocoapods

To integrate SundeedSpotlight into your Xcode project using CocoaPods, simply add the following line to your Podfile:

pod "SundeedSpotlight"

Afterwards, run the following command:

pod install

Features

• withAbilityToTapThroughSpotlight(_ passthrough: Bool): To state whether the user interactions with the spotlighted view is enabled.
  • Parameters:
    • passthrough (Bool):
      • True: SpotlightedView (e.g: UIButton) will perform its action when tapped while in the spotlight
      • False: SpotlightedView (e.g: UIButton) will not be notified that it is tapped
• withInfoCornerRadius(_ cornerRadius: CGFloat): To specify the corner radius of the info view
  • Parameters:
    • cornerRadius: A number to specify the corner radius of the info view
• withBackgroundColor(_ color: UIColor): To specify the background color of the dimmed view
  • Parameters:
    • color: A color to full view background color (e.g: UIColor.black.withAlphaComponent(0.7))
• withCustomInfoView(_ view: CustomSpotlightInfoView): To show a custom info view
  • Parameters:
    • view: A view conforming to protocol CustomSpotlightInfoView, implementing function to listen to changes happening. (e.g: didMoveToItem)
• addView(_ view: UIView, withInfo info: String? = nil, withUserInfo: [String: Any?] = [:], withCustomRadius radius: CGFloat? = nil): Add a spotlighted view (UIView) with parameters sent to customize it
  • Parameters:
    • view: A view that will be in the middle of the spotlight
    • info: Value of the string shown in the DefaultInfoView
    • userInfo: Dictionary containing any object that will be passed the the CustomSpotlightInfoView to maximize the customization
    • radius: If specified, the spotlight will be a full circle with the chosen radius, otherwise, the spotlight will be an ellipse circuling exactly the spotlightedView
• addTabBarItem(at index: Int, in tabBar: UITabBar?, withInfo info: String? = nil, withUserInfo: [String: Any?] = [:], withCustomRadius radius: CGFloat? = nil): Add a tabBarItem by passing the tabBar with a specific index
  • Parameters:
    • index: An integer indicating the index of the chosen tabBarItem to highlight
    • tabBar: The tabBar containing the tabBarItem to highlight
    • info: Value of the string shown in the DefaultInfoView
    • userInfo: Dictionary containing any object that will be passed the the CustomSpotlightInfoView to maximize the customization
    • radius: If specified, the spotlight will be a full circle with the chosen radius, otherwise, the spotlight will be an ellipse circuling exactly the spotlightedView
• wait(for string: String): To indicate to the library that it should wait for a certain event to happen (e.g: an API call) before continuing the journey
  • Parameters:
    • string: An identifier to wait for, to be sent with the 'continue' function
• func continue(for string: String): To indicate to the library that the event that it was waiting for was done (e.g: an AI call)
  • Parameters:
    • string: The identifier used to wait, so the library knows that it can continue the journey
• waitForInsertion(): To indicate to the library that other spotlighted views will be inserted and that it should wait for them (e.g: when navigating back and forth between ViewControllers holding spotlighted views in a journey)
• insertView(_ view: UIView, withInfo info: String? = nil, withUserInfo: [String: Any?] = [:], withCustomRadius radius: CGFloat? = nil): Insert a spotlighted view (UIView) in an already running Spotlight journey with parameters sent to customize it
  • Parameters:
    • view: A view that will be in the middle of the spotlight
    • info: Value of the string shown in the DefaultInfoView
    • userInfo: Dictionary containing any object that will be passed the the CustomSpotlightInfoView to maximize the customization
    • radius: If specified, the spotlight will be a full circle with the chosen radius, otherwise, the spotlight will be an ellipse circuling exactly the spotlightedView
• insertTabBarItem(at index: Int, in tabBar: UITabBar?, withInfo info: String? = nil, withUserInfo: [String: Any?] = [:], withCustomRadius radius: CGFloat? = nil): Insert a tabBarItem, in an already running Spotlight journey, by passing the tabBar with a specific index
  • Parameters:
    • index: An integer indicating the index of the chosen tabBarItem to highlight
    • tabBar: The tabBar containing the tabBarItem to highlight
    • info: Value of the string shown in the DefaultInfoView
    • userInfo: Dictionary containing any object that will be passed the the CustomSpotlightInfoView to maximize the customization
    • radius: If specified, the spotlight will be a full circle with the chosen radius, otherwise, the spotlight will be an ellipse circuling exactly the spotlightedView
• show(): Add the previously added views and tabBarItems into the Spotlight journey, either added at the beginning or inserted in between (with insert functions)

Supported Items

• UIView
• TabBarItem

Documentation

import UIKit

class ViewController: UIViewController {
    @IBOutlet weak var label: UILabel!
    @IBOutlet weak var label1: UILabel!
    @IBOutlet weak var button: UIButton!
    static let sundeedWalkthrough = SundeedWalkthrough()
    override func viewDidLoad() {
        super.viewDidLoad()
        ViewController.sundeedWalkthrough
            .withAbilityToTapThroughSpotlight(true)
            .withInfoCornerRadius(40)
            .withBackgroundColor(UIColor.black.withAlphaComponent(0.8))
            .withCustomInfoView(WalkthroughCustomView())
            .addView(label, withInfo: "1",
                            withCustomRadius: 80)
            .addTabBarItem(at: 1,
                           in: self.tabBarController?.tabBar,
                           withInfo: "2",
                           withCustomRadius: 40) // This will make the user tap on the second item in the tabBar, thus you will move to the secondViewController
            .waitForInsertion() // This will tell the library that second ViewController will insert some of its spotlightedViews here
            .addView(button, withInfo: "7")
            .wait(for: "label1")
            .addView(label1, withInfo: "8")
            .show()
    }
    
    @IBAction func didPress(_ sender: Any) {
        print("button pressed")  // This will be printed because abilityToTapThroughSpotlight was set to true
        DispatchQueue.main.asyncAfter(deadline: .now()+2) {
            self.label1.isHidden = false
            ViewController.sundeedWalkthrough.continue(for: "label1") // This shal tell the library to continue the flow after waiting 2 seconds
        }
    }
}

class SecondViewController: UIViewController {
    @IBOutlet weak var label1: UILabel!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        ViewController.sundeedWalkthrough
            .insertView(self.label1, withInfo: "3")
            .insertTabBarItem(at: 0,
                              in: self.tabBarController?.tabBar,
                              withInfo: "6",
                              withCustomRadius: 40) // This will make the user tap on the tabBarItem at 0 and go back to the first ViewController
        .show() // This will tell the library to add label1 and tabBarItem at 0 to the flow in the current flow
    }
}

CustomSpotlightInfoView

An example for a custom info view instead of the default one

class WalkthroughCustomView: UIView, CustomWalkthroughInfoView {
    @IBOutlet weak var titleLabel: UILabel!
    @IBOutlet weak var subtitleLabel: UILabel!
    @IBOutlet weak var descriptionLabel: UILabel!
    
    //manager variable is optional, you only need to add it if you wish to have a "Next" or "Skip" buttons and to control the flow manually.
    var manager: SpotlightInfoViewManager? = InfoViewManager()
    
    override init(frame: CGRect) {
        super.init(frame: frame)
        commonInit()
    }
    required public init?(coder: NSCoder) {
        super.init(coder: coder)
        commonInit()
    }
    private func commonInit() {
        fromNib()
        self.backgroundColor = .clear // set to Clear to remove the borders and the small arrow pointing to the spotlighted view
    }
    func walkthroughIsWaitingForInsertion() {
        self.titleLabel.text = "Waiting..."
        self.subtitleLabel.text = ""
        self.descriptionLabel.text = ""
    }
    func walkthroughDoneWaitingForInsertion() {
        print("walkthroughDoneWaitingForInsertion")
    }
    func walkthroughDidMoveToItem(at index: Int,
                                  withInfo info: String?,
                                  withUserInfo userInfo: [String : Any?]) {
        self.descriptionLabel.text = info
        if let title = userInfo["title"] as? String,
            let subtitle = userInfo["subtitle"] as? String {
                self.titleLabel.text = title
                self.subtitleLabel.text = subtitle
        }
    }
    func walkthroughIsWaiting(for identifier: String) {
        print("waiting for API")
    }
    func walkthroughDidContinue(for identifier: String) {
        print("api responded and the flow continued")
    }
    @IBAction func skipButtonPressed(_ sender: Any) {
        self.manager?.skip()
    }
    
    @IBAction func nextButtonPressed(_ sender: Any) {
        self.manager?.next()
    }
}

License

MIT

sundeedspotlight's Issues

Support for UITableView

How can I highlight the UIButton from UITableViewCell?

Doesn't work on UIRemoteKeyboardWindow

Library doesn't show anything if UIApplication.shared.windows.last is UIRemoteKeyboardWindow.
It works fine when I restart the application and if UIApplication.shared.windows.last is UITextEffectsWindow.