Cheat Sheet

Cheat Sheet for DownloadListController

Custom cell content:

Example 1:

cellImageViewStyle = .thumbnail 
cellAccessoryButtonStyle = .icon   
allowsTrackingSpeed = true

Example 2:

cellImageViewStyle = .index     
cellAccessoryButtonStyle = .title  
allowsTrackingSpeed = true

Example 3:

cellImageViewStyle = .none      
cellAccessoryButtonStyle = .none   
allowsTrackingSpeed = false

All properties to custom cell content:

isFileNamePriorThanURL: display file name or URL in textLabel
cellImageViewStyle: display thumbnail or index in imageView
fileThumbnailShape: select thumbnail shape if imageView displays thumbnail
cellAccessoryButtonStyle: display an icon or a title in custom button
allowsTrackingDownloadDetail: display some info in detailTextLabel or not
allowsTrackingSpeed: display download speed or not
allowsTrackingProgress: display a progress view or not

Above examples are DownloadTrackerCell, which is the default UITableViewCell used in DownloadListController. If you want custom UITableViewCell class to be compatible with above properies, reference to protocol DownloadActivityTrackable. Three perporties in front are compatible with all UITableViewCell types.

Custom Button in DownloadTrackerCell

This is a typical DownloadTrackerCell:

Now I want to change button icon and action method, like below:

// configure cell in init method
let listVC = DownloadListController.init(
                 downloadManager: downloadManager,
                 configureCell: { trackerCell, indexPath, URLString in
                     trackerCell.accessoryButton?.setImage(icon, for: .normal)
              })
// cellAccessoryButtonStyle must be .custom, otherwise above configuration for
// button appearance will be overrided in other styles.
listVC.cellAccessoryButtonStyle = .custom
// handle touch event
listVC.accessoryButtonTouchHandler = { tableView, cell, button in
    /* custom button action */
}

Custom Thumbnial for file

If cellImageViewStyle = .thumbnail, DownloadListController displays an image in cell's imageView. If file is not image or video, it displays a file type icon like below:

Sometimes you want to show some thing different, e.g., an album cover for the song, like below:

SDEDownloadManager allows you to set custom thumbnail(except for image file) by:

setCustomThumbnail(_ thumbnail: UIImage, forTask URLString: String, cacheInMemoryOnly: Bool)

Here is its document. If cacheInMemoryOnly = false, thumbnail will be stored. If you display a list of files which have same thumbnail, e.g., songs in an album, I suggest that cacheInMemoryOnly = true because there will be one copy of image object only in memory if you pass the same image object in method.

Use Custom UITableViewCell

If DownloadTrackerCell can't satisfy your needs, use custom UITableViewCell.

let listVC = DownloadListController.init(
                 downloadManager: downloadManager,
                 tableViewStyle: .plain,
                 registerCellClasses: [CustomTableViewCell.self],
                 configureCell: { tableView, indexPath, URLString in
                      return tableView.dequeueReusableCell(withIdentifier: identifier, for: indexPath)
             })

If you want your custom UITableViewCell to track download activity like DownloadTrackerCell, implement some methods in protocol DownloadActivityTrackable:

func updateDetailInfo(_ info: String?)
func updateSpeedInfo(_ info: String?)
func updateProgressValue(_ progress: Float)

If implement all methods in protocol DownloadActivityTrackable, you get another DownloadTrackerCell.

How to implment cell(from NeteaseMusic) below? Call it NeteaseMusicCell.

1. It has a check mark view which changes dynamically with download progress. Its dynamic change could be implemented in protocol method updateProgressValue(_ progress: Float).
2. It displays file quality, singer and album. SDEDownloadManager won't fetch these info by itself, you must fetch it.

Add File Meta Info

SDEDownloadManager fetch file meta info when it download a new file. Sometimes there is no info what you want, for example, in above cell, song file quality, album and singer. SDEDownloadManager leave an interface to fetch file meta info: fetchMetaInfoHandler.

downloadManager.fetchMetaInfoHandler = { URLString in
    let fetchURLRequest = NSMutableURLRequest(url: URL(string: URLString)!)
    fetchURLRequest.httpMethod = "HEAD"
    URLSession.shared.dataTask(with: fetchURLRequest as URLRequest, completionHandler: {data, response, error in
        /* Fetch music singer and album */
        // Add meta info. TIFileDisplayNameStringKey and TIFileIntroStringKey are reserved strings
        // to update file info.
        var metaInfo: Dictionary<String, Any> = [:]
        metaInfo[TIFileDisplayNameStringKey] = "Stand By Me"
        metaInfo[TIFileIntroStringKey] = "Florence + The Machine - Songs from Final Fantasy XV"
        metaInfo["FileQuality"] = "SQ"
        metaInfo["Singer"] = "Florence + The Machine"
        mataInfo["Album"] = "Final Fantasy XV"
        downloadManager.updateMetaInfo(metaInfo, forTask: URLString)
    }).resume()
}

Return to DownloadListController, use custom UITableViewCell NeteaseMusicCell:

let musicListVC = DownloadListController.init(
                      downloadManager: downloadManager,
                      tableViewStyle: .plain,
                      registerCellClasses: [NeteaseMusicCell.self],
                      configureCell: { tableView, indexPath, URLString in
                          let cell = tableView.dequeueReusableCell(withIdentifier: identifier, for: indexPath)
                          let fileIntro = downloadManager.fileMetaInfo(forTask: URLString, about: TIFileIntroStringKey) as? String
                          cell.detailTextLabel?.text = fileIntro
                          /* Set quality symbol in the NeteaseMusicCell */
                          return cell
                      })
// If following property is ture, `updateDetailInfo(_ info: String?)` will be called. Of course,
// if NeteaseMusicCell doesn't implement this method, nothing happen. If your custom UITableViewCell
// doesn't need to display dynamic content in detailTextLabel, configuring its content in init method
// is a better way.
musicListVC.allowsTrackingDownloadDetail = false

Custom Selection and Track with Cell imageView

Custom selection behavior in DownloadListController by didSelectCellHandler and didDeselectCellHandler.

// DownloadListController's tableView is disabled to select cell by default.
listVC.tableView.allowsSelection = true
listVC.didSelectCellHandler = { _, indexPath, _ in
    // Only one cell can be replaced at the same time. 
    // And after a new cell is replaced, the old cell is restored.
    listVC.replaceIndexOfCell(at: indexPath, withImage: pacman)
}