FUIListPickerTableViewController
open class FUIListPickerTableViewController : UITableViewController, UISearchResultsUpdating, UISearchBarDelegate, 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, theUINavigationController
of this view controller will be returned if it is not nil. Otherwise, the rootUINavigationController
from thekeyWindow
, 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 aFUIListPickerFormCell
.The default is
nil
, in which case, the invokingFUIListPickerFormCell
will be reloaded from itstableView
using thetableView.reloadRows
API when the selection is done. Otherwise, the handler closure is invoked.Note
The developer needs to set this property when thedataSource
of thetableView
hosting theFUIListPickerFormCell
is anUITableViewDiffableDataSource
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 andallowsMultipleSelection
false.Declaration
Swift
public var onSelectionHandler: ((Int) -> Void)?
-
The block is to be invoked when selection is made with
isDataSourceRequiringUniqueIdentifiers
false andallowsMultipleSelection
true.Declaration
Swift
public var onMultipleSelectionHandler: (([Int]) -> Void)?
-
The block is to be invoked when selection is made with
isDataSourceRequiringUniqueIdentifiers
true andallowsMultipleSelection
false.Declaration
Swift
public var onUuidSelectionHandler: ((String) -> Void)?
-
The block is to be invoked when selection is made with
isDataSourceRequiringUniqueIdentifiers
true andallowsMultipleSelection
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’stableView
.Declaration
Swift
public var emptyStateView: UIView?
-
Adjusts the tableview’s
contentOffset
when search is canceled.The default is
true
. When search is canceled, iOS sometimes may move thecontentOffset
of the tableview to a value whick is not desirable. Set this property to true to adjust thecontentOffset
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 theFUIListPicker
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 theFUIListPicker
is false.Declaration
Swift
public func selectItem(_ uniqueIdentifier: String)
Parameters
uniqueIdentifier
The unique identifier for the selected item.