UISearchBar Class Reference

Inherits from
UIView : UIResponder : NSObject
Conforms to
NSCoding (UIView)
UIAppearance (UIView)
UIAppearanceContainer (UIView)
NSObject (NSObject)
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Declared in
UISearchBar.h
Related sample code

Overview

The UISearchBar class implements a text field control for text-based searches. The control provides a text field for entering text, a search button, a bookmark button, and a cancel button. The UISearchBar object 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

In iOS v5.0 and later, you can customize the appearance of search bars using the methods listed in “Customizing Appearance.” You can customize the appearance of all search bars using the appearance proxy ([UISearchBar appearance]), or just of a single bar.

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.

Tasks

Text Content

Display Attributes

Text Input Properties

Button Configuration

Scope Buttons

Delegate

Customizing Appearance

Properties

autocapitalizationType

The auto-capitalization style for the text object.

@property(nonatomic) UITextAutocapitalizationType autocapitalizationType
Discussion

This property determines at what times the Shift key is automatically pressed, thereby making the typed character a capital letter. The default value is UITextAutocapitalizationTypeNone.

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

autocorrectionType

The auto-correction style for the text object.

@property(nonatomic) UITextAutocorrectionType autocorrectionType
Discussion

This property determines whether auto-correction is enabled or disabled during typing. With auto-correction enabled, the text object tracks unknown words and suggests a replacement candidate to the user, replacing the typed text automatically unless the user explicitly overrides the action.

The default value is UITextAutocorrectionTypeDefault, which for most input methods results in auto-correction being enabled.

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

backgroundImage

The background image for the search bar.

@property(nonatomic, retain) UIImage *backgroundImage
Discussion

Images that are 1 point wide or stretchable images are stretched, otherwise the image is tiled.

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

barStyle

The style that specifies the receiver’s appearance.

@property(nonatomic) UIBarStyle barStyle
Discussion

See UIBarStyle for possible values. The default value is UIBarStyleDefault.

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

delegate

The search bar’s delegate object.

@property(nonatomic, assign) id<UISearchBarDelegate> delegate
Discussion

The delegate should conform to the UISearchBarDelegate protocol. Set this property to further modify the behavior. The default value is nil.

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

inputAccessoryView

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

@property (nonatomic, readwrite, retain) UIView *inputAccessoryView
Discussion

The default value is nil. When non-nil, this property represents a custom input accessory view that will be placed onto the search bar’s system-supplied keyboard.

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

keyboardType

The keyboard style associated with the text object.

@property(nonatomic) UIKeyboardType keyboardType
Discussion

Text objects can be targeted for specific types of input, such as plain text, email, numeric entry, and so on. The keyboard style identifies what keys are available on the keyboard and which ones appear by default.

The default value is UIKeyboardTypeDefault.

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

placeholder

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

@property(nonatomic, copy) NSString *placeholder
Discussion

The default value is nil.

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

prompt

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

@property(nonatomic, copy) NSString *prompt
Discussion

The default value is nil.

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

scopeBarBackgroundImage

The background image for the scope bar.

@property(nonatomic, retain) UIImage *scopeBarBackgroundImage
Discussion

Images that are 1 point wide or stretchable images are stretched, otherwise the image is tiled.

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

scopeButtonTitles

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

@property(nonatomic, copy) NSArray *scopeButtonTitles
Discussion

The order of the strings in the array indicates the order that the corresponding buttons will be displayed, from left to right. The index in the array corresponds to the index used in selectedScopeButtonIndex.

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

searchFieldBackgroundPositionAdjustment

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

@property(nonatomic) UIOffset searchFieldBackgroundPositionAdjustment
Availability
  • Available in iOS 5.0 and later.
Declared In
UISearchBar.h

searchResultsButtonSelected

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

@property(nonatomic, getter=isSearchResultsButtonSelected) BOOL searchResultsButtonSelected
Discussion

The default value is NO.

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

searchTextPositionAdjustment

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

@property(nonatomic) UIOffset searchTextPositionAdjustment
Availability
  • Available in iOS 5.0 and later.
Declared In
UISearchBar.h

selectedScopeButtonIndex

The index of the selected scope button.

@property(nonatomic) NSInteger selectedScopeButtonIndex
Discussion

The indexes of the scope buttons are determined by the indexes of the strings in scopeButtonTitles.

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

showsBookmarkButton

A Boolean value indicating whether the bookmark button is displayed.

@property(nonatomic) BOOL showsBookmarkButton
Discussion

The default value is NO.

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

showsCancelButton

A Boolean value indicating whether the cancel button is displayed.

@property(nonatomic) BOOL showsCancelButton
Discussion

The default value is NO.

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

showsScopeBar

Specifies whether the scope bar is displayed.

@property(nonatomic) BOOL showsScopeBar
Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
UISearchBar.h

showsSearchResultsButton

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

@property(nonatomic) BOOL showsSearchResultsButton
Discussion

The default value is NO.

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

spellCheckingType

The spell-checking type.

@property(nonatomic) UITextSpellCheckingType spellCheckingType
Discussion

The default value is UITextSpellCheckingTypeDefault.

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

text

The current or starting search text.

@property(nonatomic, copy) NSString *text
Discussion

The default value is nil.

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

tintColor

The color used to tint the bar.

@property(nonatomic, retain) UIColor *tintColor
Discussion

The bar style is ignored if this property is not nil. The default value is nil.

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

translucent

Specifies whether the receiver is translucent.

@property(nonatomic, assign, getter=isTranslucent) BOOL translucent
Availability
  • Available in iOS 3.0 and later.
Declared In
UISearchBar.h

Instance Methods

imageForSearchBarIcon:state:

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

- (UIImage *)imageForSearchBarIcon:(UISearchBarIcon)icon state:(UIControlState)state
Parameters
icon

An icon identifier constant.

state

A control state.

Valid states are UIControlStateNormal and UIControlStateDisabled.

Return Value

The image used for the search bar icon identified by icon in the state identified by state.

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

positionAdjustmentForSearchBarIcon:

Returns the position adjustment for a given icon.

- (UIOffset)positionAdjustmentForSearchBarIcon:(UISearchBarIcon)icon
Parameters
icon

An icon identifier constant.

Return Value

The position adjustment for the icon identified by icon.

Discussion

The offset is used to adjust the position of an icon within the search text field.

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

scopeBarButtonBackgroundImageForState:

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

- (UIImage *)scopeBarButtonBackgroundImageForState:(UIControlState)state
Parameters
state

A control state.

Return Value

The background image for the scope bar button in state.

Discussion

If the background image is an image returned from stretchableImageWithLeftCapWidth:topCapHeight: (UIImage), the cap widths are calculated from that information, otherwise, the cap width is calculated by subtracting one from the image’s width then dividing by 2. The cap widths are used as the margins for text placement. To adjust the margin use the margin adjustment methods.

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

scopeBarButtonDividerImageForLeftSegmentState:rightSegmentState:

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

- (UIImage *)scopeBarButtonDividerImageForLeftSegmentState:(UIControlState)leftState rightSegmentState:(UIControlState)rightState
Parameters
leftState

The state of the left segment for which to provide the divider image.

The state may be UIControlStateNormal or UIControlStateSelected.

rightState

The state of the right segment for which to provide the divider image.

The state may be UIControlStateNormal or UIControlStateSelected.

Return Value

The divider image to use for the combination of leftState and rightState.

Discussion

For more details, see setScopeBarButtonDividerImage:forLeftSegmentState:rightSegmentState:

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

scopeBarButtonTitleTextAttributesForState:

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

- (NSDictionary *)scopeBarButtonTitleTextAttributesForState:(UIControlState)state
Parameters
state

A control state.

Return Value

The text attributes for the search bar’ button’s title string for state.

The attributes may specify the font, text color, text shadow color, and text shadow offset, using the keys found in NSString UIKit Additions Reference.

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

searchFieldBackgroundImageForState:

Returns the search text field image for a given state.

- (UIImage *)searchFieldBackgroundImageForState:(UIControlState)state
Parameters
state

A control state.

Valid states are UIControlStateNormal and UIControlStateDisabled.

Return Value

The search text field image image to use for state.

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

setImage:forSearchBarIcon:state:

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

- (void)setImage:(UIImage *)iconImage forSearchBarIcon:(UISearchBarIcon)icon state:(UIControlState)state
Parameters
iconImage

The image to use for the search bar icon identified by icon in the state identified by state.

icon

An icon identifier constant.

state

A control state.

Valid states are UIControlStateNormal and UIControlStateDisabled.

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

setPositionAdjustment:forSearchBarIcon:

Returns the position adjustment for a given icon.

- (void)setPositionAdjustment:(UIOffset)adjustment forSearchBarIcon:(UISearchBarIcon)icon
Parameters
adjustment

The offset to use for the icon identified by icon.

icon

An icon identifier constant.

Discussion

Use this method to adjust the position of an icon within the search text field.

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

setScopeBarButtonBackgroundImage:forState:

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

- (void)setScopeBarButtonBackgroundImage:(UIImage *)backgroundImage forState:(UIControlState)state
Parameters
backgroundImage

The background image for the scope bar button in state.

state

A control state.

Discussion

For more details, see scopeBarButtonBackgroundImageForState:.

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

setScopeBarButtonDividerImage:forLeftSegmentState:rightSegmentState:

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

- (void)setScopeBarButtonDividerImage:(UIImage *)dividerImage forLeftSegmentState:(UIControlState)leftState rightSegmentState:(UIControlState)rightState
Parameters
dividerImage

The divider image to use for the combination of leftState and rightState.

leftState

The state of the left segment for which to set the divider image.

The state may be UIControlStateNormal or UIControlStateSelected.

rightState

The state of the right segment for which to set the divider image.

The state may be UIControlStateNormal or UIControlStateSelected.

Discussion

To customize the segmented control appearance you need to provide divider images to go between two unselected segments (leftSegmentState:UIControlStateNormal rightSegmentState:UIControlStateNormal), selected on the left and unselected on the right (leftSegmentState:UIControlStateSelected rightSegmentState:UIControlStateNormal), and unselected on the left and selected on the right (leftSegmentState:UIControlStateNormal rightSegmentState:UIControlStateSelected).

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

setScopeBarButtonTitleTextAttributes:forState:

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

- (void)setScopeBarButtonTitleTextAttributes:(NSDictionary *)attributes forState:(UIControlState)state
Parameters
attributes

A dictionary containing key-value pairs specifying the text attributes to use for state.

You may specify the font, text color, text shadow color, and text shadow offset, using the keys found in NSString UIKit Additions Reference.

state

A control state.

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

setSearchFieldBackgroundImage:forState:

Sets the search text field image for a given state.

- (void)setSearchFieldBackgroundImage:(UIImage *)backgroundImage forState:(UIControlState)state
Parameters
backgroundImage

The search text field image image to use for state.

state

A control state.

Valid states are UIControlStateNormal and UIControlStateDisabled.

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

setShowsCancelButton:animated:

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

- (void)setShowsCancelButton:(BOOL)showsCancelButton animated:(BOOL)animated
Parameters
showsCancelButton

YES to display the cancel button, otherwise NO.

animated

YES to use animation to change the display state of the cancel button, otherwise NO.

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

Constants

UISearchBarIcon

Constants to identify the icons used in the search bar.

typedef enum {
   UISearchBarIconSearch,
   UISearchBarIconClear,
   UISearchBarIconBookmark,
   UISearchBarIconResultsList,
} UISearchBarIcon;
Constants
UISearchBarIconSearch

Identifies the search icon.

By default, the corresponding icon is a magnifying glass.

Available in iOS 5.0 and later.

Declared in UISearchBar.h.

UISearchBarIconClear

Identifies the clear action icon.

By default, the corresponding icon is a circle containing an X.

Available in iOS 5.0 and later.

Declared in UISearchBar.h.

UISearchBarIconBookmark

Identifies the bookmarks icon.

By default, the corresponding icon is an open book.

Available in iOS 5.0 and later.

Declared in UISearchBar.h.

UISearchBarIconResultsList

Identifies the results list icon.

By default, the corresponding icon is a list lozenge icon.

Available in iOS 5.0 and later.

Declared in UISearchBar.h.



© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)

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