iOS Developer Library — Pre-Release

Developer

UIKit Framework Reference UISearchDisplayController Class Reference

Options
Deployment Target:

On This Page
Language:

UISearchDisplayController

Inheritance


Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 3.0 and later.
Deprecated in iOS 8.0.

Important: UISearchDisplayController is deprecated in iOS 8. (Note that UISearchDisplayDelegate is also deprecated.) To manage the presentation of a search bar and display search results in iOS 8 and later, instead use UISearchController.

A search display controller manages the display of a search bar, along with a table view that displays search results.

You initialize a search display controller with a search bar and a view controller responsible for managing the data to be searched. When the user starts a search, the search display controller superimposes the search interface over the original view controller’s view and shows the search results in its table view.

In addition to managing the searchable data, the original view controller typically plays four more roles you need to fill when using a search display controller. Those roles are the following:

  1. Data source for the search results table view (searchResultsDataSource), which provides the data for the results table.

  2. Delegate for the search results table view (searchResultsDelegate), which responds to the user’s selection of an item in the results table.

  3. Delegate for the search display controller (delegate), which responds to events such the starting or ending of a search, and the showing or hiding of the search interface.

    As a convenience, this delegate may also be told about changes to the search string or search scope, so that the results table view can be reloaded.

  4. Delegate for the search bar (delegate described in UISearchBar Class Reference), which responds to changes in search criteria.

Typically, you initialize a search display controller from a view controller (usually an instance of UITableViewController) that’s displaying a list. See the Simple UISearchBar with State Restoration sample code project for an example of how to configure a search display controller in Interface Builder. To perform configuration programmatically, set self for the search display controller’s view controller and search results data source and delegate, as shown here:

  • searchController = [[UISearchDisplayController alloc]
  • initWithSearchBar:searchBar contentsController:self];
  • searchController.delegate = self;
  • searchController.searchResultsDataSource = self;
  • searchController.searchResultsDelegate = self;

If you follow this pattern, then in the table view data source and delegate methods you can check the methods’ table view argument to determine which table view is sending the message:

  • - (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section {
  • if (tableView == self.tableView) {
  • return ...;
  • }
  • // If necessary (if self is the data source for other table views),
  • // check whether tableView is searchController.searchResultsTableView.
  • return ...;
  • }

Starting in iOS 7.0, you can use a search display controller with a navigation bar (an instance of the UINavigationBar class) by configuring the search display controller’s displaysSearchBarInNavigationBar and navigationItem properties.

  • Returns a display controller initialized with the given search bar and contents controller.

    Declaration

    Swift

    init(searchBar searchBar: UISearchBar!, contentsController viewController: UIViewController!)

    Objective-C

    - (instancetype)initWithSearchBar:(UISearchBar *)searchBar contentsController:(UIViewController *)viewController

    Parameters

    searchBar

    A search bar.

    The search bar must not currently be associated with another search display controller.

    viewController

    The view controller that manages display of the original contents that are to be searched.

    The view controller must not currently be associated with another search display controller.

    Return Value

    A search display controller initialized with the given search bar and contents controller.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 8.0.

  • active active (iOS 8.0) Property

    The visibility state of the search interface.

    Declaration

    Swift

    var active: Bool

    Objective-C

    @property(nonatomic, getter=isActive) BOOL active

    Discussion

    The default value is NOfalse.

    If you set this value directly, any change is performed without animation. Use setActive:animated: if a change in state should be animated.

    When the user focus in the search field of a managed search bar, the search display controller automatically displays the search interface. You can use this property to force the search interface to appear.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 8.0.

  • Displays or hides the search interface, optionally with animation.

    Declaration

    Swift

    func setActive(_ visible: Bool, animated animated;: Bool)

    Objective-C

    - (void)setActive:(BOOL)visible animated:(BOOL)animated;

    Parameters

    visible

    YEStrue to display the search interface if it is not already displayed; NOfalse to hide the search interface if it is currently displayed.

    animated;

    YEStrue to use animation for a change in visible state, otherwise NOfalse.

    Discussion

    When the user focus in the search field of a managed search bar, the search display controller automatically displays the search interface. You can use this method to force the search interface to appear.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 8.0.

  • delegate delegate (iOS 8.0) Property

    The controller’s delegate.

    Declaration

    Swift

    unowned(unsafe) var delegate: UISearchDisplayDelegate?

    Objective-C

    @property(nonatomic, assign) id< UISearchDisplayDelegate > delegate

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 8.0.

  • searchBar searchBar (iOS 8.0) Property

    The search bar. (read-only)

    Declaration

    Swift

    var searchBar: UISearchBar! { get }

    Objective-C

    @property(nonatomic, readonly) UISearchBar *searchBar

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 8.0.

  • The view controller that manages the contents being searched. (read-only)

    Declaration

    Swift

    var searchContentsController: UIViewController! { get }

    Objective-C

    @property(nonatomic, readonly) UIViewController *searchContentsController

    Discussion

    This is typically an instance of UITableViewController.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 8.0.

  • The table view in which the search results are displayed. (read-only)

    Declaration

    Swift

    var searchResultsTableView: UITableView! { get }

    Objective-C

    @property(nonatomic, readonly) UITableView *searchResultsTableView

    Discussion

    This method creates a new table view if one does not already exist.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 8.0.

  • The data source for the table view in which the search results are displayed.

    Declaration

    Swift

    unowned(unsafe) var searchResultsDataSource: UITableViewDataSource?

    Objective-C

    @property(nonatomic, assign) id< UITableViewDataSource > searchResultsDataSource

    Discussion

    The default is nil.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 8.0.

  • The delegate for the table view in which the search results are displayed.

    Declaration

    Swift

    unowned(unsafe) var searchResultsDelegate: UITableViewDelegate?

    Objective-C

    @property(nonatomic, assign) id< UITableViewDelegate > searchResultsDelegate

    Discussion

    The default is nil.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 8.0.

  • The title for the search results view.

    Declaration

    Swift

    var searchResultsTitle: String?

    Objective-C

    @property(nonatomic, copy) NSString *searchResultsTitle

    Discussion

    The default value is nil.

    If the value is nil, the controller uses the default title string.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

    Deprecated in iOS 8.0.

  • Specifies that the navigation bar contains a search bar.

    Declaration

    Swift

    var displaysSearchBarInNavigationBar: Bool

    Objective-C

    @property(nonatomic, assign) BOOL displaysSearchBarInNavigationBar

    Discussion

    When you return YEStrue to display the search bar in a navigation bar, the system uses the search display controller’s navigationItem property and ignores the navigation item, if set, of the searchContentsController view controller. The displayed search field occupies as much width in the navigation bar as possible.

    A search bar displayed in a navigation bar cannot have a scope bar.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

    Deprecated in iOS 8.0.

  • navigationItem navigationItem (iOS 8.0) Property

    Represents the search display controller in a navigation controller’s navigation bar. (read-only)

    Declaration

    Swift

    var navigationItem: UINavigationItem! { get }

    Objective-C

    @property(nonatomic, readonly) UINavigationItem *navigationItem

    Discussion

    You can configure the navigation item as described in the UINavigationItem Class Reference, with the exception of configuring the title view.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

    Deprecated in iOS 8.0.