Class

UISearchBar

A specialized view for receiving search-related information from the user.

Declaration

@interface UISearchBar : UIView

Overview

UISearchBar provides a text field for entering text, a search button, a bookmark button, and a cancel button. A search bar does not actually perform any searches. You use a delegate, an object conforming to the UISearchBarDelegate protocol, to implement the actions when text is entered and buttons are clicked.

Customizing Appearance

You can customize the appearance of search bars one at a time, or you can use the appearance proxy ([UISearchBar appearance]) to customize the appearance of all search bars in an app.

In general, you should specify a value for the normal state to be used by other states which don’t have a custom value set. Similarly, when a property is dependent on the bar metrics (on iPhone, in landscape orientation bars have a different height from standard), you should specify a value for UIBarMetricsDefault.

Topics

Initializing the Search Bar

init

Initializes the search bar to its default state.

Handling Search Bar Interactions

delegate

The search bar’s delegate object.

UISearchBarDelegate

A collection of optional methods that you implement to make a search bar control functional.

Text Content

placeholder

The string that is displayed when there is no other text in the text field.

prompt

A single line of text displayed at the top of the search bar.

text

The current or starting search text.

Display Attributes

barStyle

A bar style that specifies the search bar’s appearance.

barTintColor

The tint color to apply to the search bar background.

searchBarStyle

A search bar style that specifies the search bar’s appearance.

tintColor

The tint color to apply to key elements in the search bar.

translucent

A Boolean value that indicates whether the search bar is translucent (YES) or not (NO).

Customizing the Keyboard Shortcut Items

inputAssistantItem

The input assistant to use for configuring the keyboard’s shortcuts bar.

Button Configuration

showsBookmarkButton

A Boolean value indicating whether the bookmark button is displayed.

showsCancelButton

A Boolean value indicating whether the cancel button is displayed.

setShowsCancelButton:animated:

Sets the display state of the cancel button optionally with animation.

showsSearchResultsButton

A Boolean value indicating whether the search results button is displayed.

searchResultsButtonSelected

A Boolean value indicating whether the search results button is selected.

Scope Buttons

scopeButtonTitles

An array of strings indicating the titles of the scope buttons.

selectedScopeButtonIndex

The index of the selected scope button.

showsScopeBar

Specifies whether the scope bar is displayed.

Customizing Appearance

backgroundImage

The background image for the search bar.

backgroundImageForBarPosition:barMetrics:

Returns the image used for the background in a given position and with given metrics.

setBackgroundImage:forBarPosition:barMetrics:

Sets the image to use for the background in a given position and with given metrics.

imageForSearchBarIcon:state:

Returns the image for a given search bar icon type and control state.

setImage:forSearchBarIcon:state:

Sets the image for a given search bar icon type and control state.

positionAdjustmentForSearchBarIcon:

Returns the position adjustment for a given icon.

setPositionAdjustment:forSearchBarIcon:

Returns the position adjustment for a given icon.

inputAccessoryView

A custom input accessory view for the keyboard of the search bar.

scopeBarBackgroundImage

The background image for the scope bar.

scopeBarButtonBackgroundImageForState:

Returns the background image for the scope bar button in a given state.

setScopeBarButtonBackgroundImage:forState:

Sets the background image for the scope bar button in a given state.

scopeBarButtonDividerImageForLeftSegmentState:rightSegmentState:

Returns the divider image to use for a given combination of left and right segment states.

setScopeBarButtonDividerImage:forLeftSegmentState:rightSegmentState:

Sets the divider image to use for a given combination of left and right segment states.

scopeBarButtonTitleTextAttributesForState:

Returns the text attributes for the search bar’s button’s title string for a given state.

setScopeBarButtonTitleTextAttributes:forState:

Sets the text attributes for the search bar’ button’s title string for a given state.

searchFieldBackgroundImageForState:

Returns the search text field image for a given state.

setSearchFieldBackgroundImage:forState:

Sets the search text field image for a given state.

searchFieldBackgroundPositionAdjustment

The offset of the search text field background in the search bar.

searchTextPositionAdjustment

The offset of the text within the search text field background.

Constants

UISearchBarIcon

Constants to identify the icons used in the search bar.

UISearchBarStyle

Specifies whether the search bar has a background.

UIBarStyle

Defines the stylistic appearance of different types of views.

UIOffset

Defines a structure that specifies an amount to offset a position.

Relationships

Inherits From

See Also

Bars

UIBarItem

An abstract superclass for items that can be added to a bar that appears at the bottom of the screen.

UIBarButtonItem

A button specialized for placement on a toolbar or tab bar.

UIBarButtonItemGroup

A set of bar button items on the shortcuts bar above the keyboard on iPad.

UINavigationBar

Navigational controls displayed in a bar along the top of the screen, usually in conjunction with a navigation controller.

UIToolbar

A control that displays one or more buttons along the bottom edge of your interface.

UITabBar

A control that displays one or more buttons in a tab bar for selecting between different subtasks, views, or modes in an app.

UITabBarItem

An item in a tab bar.

UIBarPositioning

A set of methods for defining the ways that bars can be positioned in iOS apps.

UIBarPositioningDelegate

A set of methods that support the positioning of a bar that conforms to the UIBarPositioning protocol.