UISearchBarDelegate Protocol Reference

Conforms to
NSObject
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Declared in
UISearchBar.h
Related sample code

Overview

The UISearchBarDelegate protocol defines the optional methods you implement to make a UISearchBar control functional. A UISearchBar object provides the user interface for a search field on a bar, but it’s the application’s responsibility to implement the actions when buttons are tapped. At a minimum, the delegate needs to perform the actual search when text is entered in the text field.

Tasks

Editing Text

Clicking Buttons

Scope Button

Instance Methods

searchBar:selectedScopeButtonIndexDidChange:

Tells the delegate that the scope button selection changed.

- (void)searchBar:(UISearchBar *)searchBar selectedScopeButtonIndexDidChange:(NSInteger)selectedScope
Parameters
searchBar

The search bar that was tapped.

selectedScope

The index of the selected scope button (see selectedScopeButtonIndex).

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

searchBar:shouldChangeTextInRange:replacementText:

Ask the delegate if text in a specified range should be replaced with given text.

- (BOOL)searchBar:(UISearchBar *)searchBar shouldChangeTextInRange:(NSRange)range replacementText:(NSString *)text
Parameters
searchBar

The search bar that is being edited.

range

The range of the text to be changed.

text

The text to replace existing text in range.

Return Value

YES if text in range should be replaced by text, otherwise, NO.

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

searchBar:textDidChange:

Tells the delegate that the user changed the search text.

- (void)searchBar:(UISearchBar *)searchBar textDidChange:(NSString *)searchText
Parameters
searchBar

The search bar that is being edited.

searchText

The current text in the search text field.

Discussion

This method is also invoked when text is cleared from the search text field.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISearchBar.h

searchBarBookmarkButtonClicked:

Tells the delegate that the bookmark button was tapped.

- (void)searchBarBookmarkButtonClicked:(UISearchBar *)searchBar
Parameters
searchBar

The search bar that was tapped.

Discussion

There is no automatic bookmark support provided by the search bar. It’s the application’s responsibility to implement this method to perform some action if the bookmark button is tapped by the user.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UISearchBar.h

searchBarCancelButtonClicked:

Tells the delegate that the cancel button was tapped.

- (void)searchBarCancelButtonClicked:(UISearchBar *)searchBar
Parameters
searchBar

The search bar that was tapped.

Discussion

Typically, you implement this method to dismiss the search bar.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UISearchBar.h

searchBarResultsListButtonClicked:

Tells the delegate that the search results list button was tapped.

- (void)searchBarResultsListButtonClicked:(UISearchBar *)searchBar
Parameters
searchBar

The search bar that was tapped.

Availability
  • Available in iOS 3.2 and later.
Declared In
UISearchBar.h

searchBarSearchButtonClicked:

Tells the delegate that the search button was tapped.

- (void)searchBarSearchButtonClicked:(UISearchBar *)searchBar
Parameters
searchBar

The search bar that was tapped.

Discussion

You should implement this method to begin the search. Use the text property of the search bar to get the text. You can also send becomeFirstResponder to the search bar to begin editing programmatically.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISearchBar.h

searchBarShouldBeginEditing:

Asks the delegate if editing should begin in the specified search bar.

- (BOOL)searchBarShouldBeginEditing:(UISearchBar *)searchBar
Parameters
searchBar

The search bar that is being edited.

Return Value

YES if an editing session should be initiated, otherwise, NO.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UISearchBar.h

searchBarShouldEndEditing:

Asks the delegate if editing should stop in the specified search bar.

- (BOOL)searchBarShouldEndEditing:(UISearchBar *)searchBar
Parameters
searchBar

The search bar that is being edited.

Return Value

YES if editing should stop, otherwise NO.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UISearchBar.h

searchBarTextDidBeginEditing:

Tells the delegate when the user begins editing the search text.

- (void)searchBarTextDidBeginEditing:(UISearchBar *)searchBar
Parameters
searchBar

The search bar that is being edited.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UISearchBar.h

searchBarTextDidEndEditing:

Tells the delegate that the user finished editing the search text.

- (void)searchBarTextDidEndEditing:(UISearchBar *)searchBar
Parameters
searchBar

The search bar that is being edited.

Discussion

Typically, you implement this method to perform the text-based search.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UISearchBar.h


© 2010 Apple Inc. All Rights Reserved. (Last updated: 2010-04-28)

Did this document help you? Yes It's good, but... Not helpful...