FUIListPickerTableViewController

open class FUIListPickerTableViewController : UITableViewController, UISearchResultsUpdating, UISearchBarDelegate
extension FUIListPickerTableViewController: FUIBarcodeScanViewControllerDelegate
extension FUIListPickerTableViewController: UISheetPresentationControllerDelegate

This FUIListPickerTableViewController is to show a list of table view cells to let user select one of the cell. Developer needs to provide implementation of FUIListPickerDataSource, and FUIListPickerSearchResultsUpdating if search is enabled, in order to use FUIListPickerTableViewController.

If the isDismissedOnSelection property is set to true, and the allowsMultipleSelection property is set to false, then when user selected one cell by tapping the displayed cell, the onSelectionHandler property will be invoked to notify the user selection. The table view will then be dismissed.

There will be a “Done” button shown in the navigation bar if the isDismissedOnSelection property is set to false or the allowsMultipleSelection property is set to true. The onSelectionHandler property will be invoked after user tapped the “Done” button if the allowsMultipleSelection property is set to false, or the onMultipleSelectionHandler property will be invoked if the allowsMultipleSelection property is set to true. Then the table view will be dismissed.

There will be a “Select All” button in the “All” section header, if multiple selections is allowed and not all items are selected. All items are selected when the “Select All” button is tapped. Once all items are selected, the button title will change to “Deselect All”. All items are de-selected when “Deselect All” button is tapped.

Also, a “Deselect All” button will be in the “Selected” section header when multiple selections is allowed. The “Selected” section will appear if the items in the list could not be displayed in one screen, and there are one or more items selected. All selected items will be de-selected when “Deselect All” button is tapped.

Here is a code snippet of a typical usage:


let listPickerTableViewController = createInstanceFromStoryboard()
var listPicker = listPickerTableViewController.listPicker

listPicker.title = "Magic School"
listPicker.register(FUIObjectTableViewCell.self, forCellReuseIdentifier: FUIObjectTableViewCell.reuseIdentifier)
listPicker.dataSource = self.objectCellListPickerDataSource
listPicker.prompt = "Select One"
listPicker.estimatedRowHeight = 98

listPicker.isSearchEnabled = true
listPicker.searchResultsUpdating = self.objectCellListPickerDataSource
listPicker.isBarcodeScannerEnabled = true
listPicker.barcodeScanMode = .all
listPicker.barcodeScanResultTransformer = { (scanString) -> String in
return "S"
}

listPickerTableViewController.onSelectionHandler = {
self.select1Result.text = self.objectCellListPickerDataSource.descriptionForSelectedItems(at: [$0])
}
listPickerTableViewController.showsCancelButton = true
listPickerTableViewController.isDismissedOnSelection = false

// Select item at index 4 as default, which is the 5th item.
listPickerTableViewController.selectItem(4)

let navController = UINavigationController(rootViewController: listPickerTableViewController)
self.present(navController, animated: true, completion: nil)

Theming

Supported style classes

fdlFUIListPickerTableViewController
fdlFUIListPickerTableViewController_cancelItem
fdlFUIListPickerTableViewController_sectionHeaderTitleLabel
fdlFUIListPickerTableViewController_listTextLabel

  • Creates a FUIListPickerTableViewController object from storyboard.

    Declaration

    Swift

    public class func createInstanceFromStoryboard() -> FUIListPickerTableViewController

    Return Value

    The instantiated FUIListPickerTableViewController object.

  • The effective UINavigationController.

    Developer could set this to the UINavigationController for this view controller. If developer did not set this value, the UINavigationController of this view controller will be returned if it is not nil. Otherwise, the root UINavigationController from the keyWindow, if any, will be returned.

    Declaration

    Swift

    public var effectiveNavigationController: UINavigationController? { get set }

  • Customization handler for section header view.

    Developers can use this handler to customize the section header view. The first parameter is the section index, the second parameter is the section header view, the third parameter indicates whether this is a selected section, and the fourth parameter is the type of the action button.

    Declaration

    Swift

    public var sectionHeaderCustomizationHandler: ((Int, FUIListPickerHeaderView, Bool, FUIListPickerSectionHeaderButtonType) -> Void)?

  • This property indicates whether the “Cancel” button is shown in the search bar or not when search is active.

    The default is true.

    Declaration

    Swift

    public var showsCancelButtonOnSearchBar: Bool

  • The FUIListPicker for this controller.

    Declaration

    Swift

    public var listPicker: FUIListPicker

  • This property indicates whether the selection mark is on the leading side or not.

    The default value is false, meaning that there will be a check mark on the trailing side of the cell for a selected item.

    Otherwise, when the value is true, there will be an empty circle on the leading side of the cell for a unselected item, and a circle with a check mark in the center for a selected item.

    Declaration

    Swift

    open var usesLeadingSelectionStyle: Bool

  • This property indicates whether an anchor button is to be displayed.

    The anchor button floats on top of the selection table view. When tapped, it takes the user to the top of the list.

    • The anchor button is only available in full model sheet view.
    • It will only appear if a selection is made and if the selected section is outside of the visible area.
    • It has a number indicating the number of items selected.

    The default is true.

    Declaration

    Swift

    open var showsAnchorButton: Bool

  • The custom title format for the anchor button.

    If this property is nil, the default title format is localized “Selected (%d)”.

    Declaration

    Swift

    open var anchorButtonTitleFormat: String?

  • This property indicates whether an alert controller will be displayed when the user dismisses the selection table view without tapping the “Cancel” or “Apply” buttons in modal presentation.

    The default is true.

    Declaration

    Swift

    open var showsAlertOnDismiss: Bool

  • The custom message of the alert when it is dismissed.

    If this is nil, the default is the localized string: “Are you sure you want to discard your selections?”.

    Declaration

    Swift

    open var alertMessage: String?

  • The custom title for the “Discard Changes” button in the dismiss alert.

    If this is nil, the default is the localized string: “Discard Changes”.

    Declaration

    Swift

    open var discardChangesActionTitle: String?

  • The custom title for the “Keep Editing” button in the dismiss alert.

    If this is nil, the default is the localized string: “Keep Editing”.

    Declaration

    Swift

    open var keepEditingActionTitle: String?

  • This handler closure is invoked when the selection is done and this FUIListPickerFormTableViewController is presented from a FUIListPickerFormCell.

    The default is nil, in which case, the invoking FUIListPickerFormCell will be reloaded from its tableView using the tableView.reloadRows API when the selection is done. Otherwise, the handler closure is invoked.

    Note

    The developer needs to set this property when the dataSource of the tableView hosting the FUIListPickerFormCell is an UITableViewDiffableDataSource instance. Otherwise, a crash will occur.

    The implementation of this handler should at least reload the FUIListPickerFormCell to reflect the selections.

    Declaration

    Swift

    open var didFinishSelectionHandler: (() -> Void)?

  • Undocumented

    Declaration

    Swift

    open override func viewDidDisappear(_ animated: Bool)

  • The block is to be invoked when selection is made with isDataSourceRequiringUniqueIdentifiers false and allowsMultipleSelection false.

    Declaration

    Swift

    public var onSelectionHandler: ((Int) -> Void)?

  • The block is to be invoked when selection is made with isDataSourceRequiringUniqueIdentifiers false and allowsMultipleSelection true.

    Declaration

    Swift

    public var onMultipleSelectionHandler: (([Int]) -> Void)?

  • The block is to be invoked when selection is made with isDataSourceRequiringUniqueIdentifiers true and allowsMultipleSelection false.

    Declaration

    Swift

    public var onUuidSelectionHandler: ((String) -> Void)?

  • The block is to be invoked when selection is made with isDataSourceRequiringUniqueIdentifiers true and allowsMultipleSelection true.

    Declaration

    Swift

    public var onUuidMultipleSelectionHandler: (([String]) -> Void)?

  • A boolean value indicating to show the “Cancel” button or not.

    Default is false.

    Declaration

    Swift

    public var showsCancelButton: Bool { get set }

  • The “Cancel” button on the navigation bar.

    Declaration

    Swift

    @IBOutlet
public var cancelBarButtonItem: UIBarButtonItem!

  • If this property is true, this list picker table view will be dismissed once user makes the selection.

    If this is false, there will be a “Done” button in addition to a “Cancle” button. User needs to tap the “Done” button to dismiss the list picker table view. The onSelectionHandler will then be invoked. The default is true.

    This property is ignored if allowsMultipleSelection is true.

    Declaration

    Swift

    public var isDismissedOnSelection: Bool

  • Indicates if user can select multiple values. Default is false, meaning by default user may select only one value.

    Declaration

    Swift

    public var allowsMultipleSelection: Bool { get set }

  • Indicates if empty selection is allowed.

    The default value is false, meaning by default user must select at least one item.

    Declaration

    Swift

    public var allowsEmptySelection: Bool

  • A view to be displayed when there are no items.

    The view will be added as a subview of the controller’s tableView.

    Declaration

    Swift

    public var emptyStateView: UIView?

Table view data source

  • Adjusts the tableview’s contentOffset when search is canceled.

    The default is true. When search is canceled, iOS sometimes may move the contentOffset of the tableview to a value whick is not desirable. Set this property to true to adjust the contentOffset back to top.

    Or, developer can set this to false to just use the standard iOS behavior.

    Declaration

    Swift

    public var adjustsContentOffsetOnCancelSearch: Bool

  • Undocumented

    Declaration

    Swift

    open override func tableView(_ tableView: UITableView, heightForHeaderInSection section: Int) -> CGFloat

  • Select an item with an index programatically.

    This is to be used to pre-select an item before presenting this controller. Note that this function does nothing when the isDataSourceRequiringUniqueIdentifiers property of the FUIListPicker is true.

    Declaration

    Swift

    public func selectItem(_ index: Int)

    Parameters

    index

    The index for the selected item in the list.

  • Select an item using unique identifier programatically.

    This is to be used to pre-select an item before presenting this controller. Note that this function does nothing when the isDataSourceRequiringUniqueIdentifiers property of the FUIListPicker is false.

    Declaration

    Swift

    public func selectItem(_ uniqueIdentifier: String)

    Parameters

    uniqueIdentifier

    The unique identifier for the selected item.