UISearchDisplayController Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 3.0 and later.
Declared in
UISearchDisplayController.h
Related sample code

Overview

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.

Tasks

Initializing a Search Bar

Displaying the Search Interface

Configuring a Search Bar

Properties

active

The visibility state of the search interface.

@property(nonatomic, getter=isActive) BOOL active
Discussion

The default value is NO.

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.

Availability
  • Available in iOS 3.0 and later.
Declared In
UISearchDisplayController.h

delegate

The controller’s delegate.

@property(nonatomic, assign) id<UISearchDisplayDelegate> delegate
Availability
  • Available in iOS 3.0 and later.
Declared In
UISearchDisplayController.h

displaysSearchBarInNavigationBar

Specifies that the navigation bar contains a search bar.

@property(nonatomic, assign) BOOL displaysSearchBarInNavigationBar
Discussion

When you return YES 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.

Availability
  • Available in iOS 7.0 and later.
Declared In
UISearchDisplayController.h

navigationItem

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

@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.

Availability
  • Available in iOS 7.0 and later.
Declared In
UISearchDisplayController.h

searchBar

The search bar. (read-only)

@property(nonatomic, readonly) UISearchBar *searchBar
Availability
  • Available in iOS 3.0 and later.
Declared In
UISearchDisplayController.h

searchContentsController

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

@property(nonatomic, readonly) UIViewController *searchContentsController
Discussion

This is typically an instance of UITableViewController.

Availability
  • Available in iOS 3.0 and later.
Declared In
UISearchDisplayController.h

searchResultsDataSource

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

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

The default is nil.

Availability
  • Available in iOS 3.0 and later.
Declared In
UISearchDisplayController.h

searchResultsDelegate

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

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

The default is nil.

Availability
  • Available in iOS 3.0 and later.
Declared In
UISearchDisplayController.h

searchResultsTableView

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

@property(nonatomic, readonly) UITableView *searchResultsTableView
Discussion

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

Availability
  • Available in iOS 3.0 and later.
Declared In
UISearchDisplayController.h

searchResultsTitle

The title for the search results view.

@property(nonatomic, copy) NSString *searchResultsTitle
Discussion

The default value is nil.

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

Availability
  • Available in iOS 5.0 and later.
Declared In
UISearchDisplayController.h

Instance Methods

initWithSearchBar:contentsController:

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

- (id)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.

Availability
  • Available in iOS 3.0 and later.
Declared In
UISearchDisplayController.h

setActive:animated:

Displays or hides the search interface, optionally with animation.

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

YES to display the search interface if it is not already displayed; NO to hide the search interface if it is currently displayed.

animated;

YES to use animation for a change in visible state, otherwise NO.

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.

Availability
  • Available in iOS 3.0 and later.
Declared In
UISearchDisplayController.h