---

Adding a Search Field to Your Application

You can create a search field programatically, but the easiest way to add a search field to your application is to use Interface Builder. Simply drag a search field from the Cocoa-Text palette to your window. and add it to a window.

Use the Attributes pane of the Show Info panel to set search-field-specific attributes:

• Placeholder, which specifies text that appears in the search field until the user enters text. You can also programmatically send the setPlaceholderString: message to the search field’s cell.

• Max Recents, which specifies the maximum number of recent searches to show in the recents menu. This value can be from 0 to 254, and defaults to 10. When the limit is exceeded, the oldest search string on the menu is dropped. Setting the value to a negative value uses the default value; a value greater than 254 sets the maximum to 254. The recents list is trimmed if there are more entries than the new maximum. You can also programmatically send the setMaximumRecents: message to the search field’s cell.

• Auto Save Name, which if set, the recent search list is saved to an application preference using the name provided, and restored the next time the recents list is needed for the popup menu. You can also programmatically send the setRecentsAutosaveName: message. Setting the autosave name to nil does not clear out any saved lists. Setting the autosave name to a valid string discards any current recents and loads the recents from the user defaults.

• Sends Whole Search String, which specifies whether the search field sends the action message when the user presses the Return key or if it sends the message upon each keystroke (incremental search). You can also programmatically send the setSendsWholeSearchString: message to the search field’s cell. By default, the cell’s action is invoked during typing after a short delay.

You can connect the a search field to a menu template. The details of the menu’s contents are described in “Configuring a Search Menu.”

You need to configure the targets and actions of the search field. This is described in “Implementing the Target.”

You can also specify that the search field use a controller to perform searches. In the Bindings pane, disclose the value binding and select the controller to bind to as well as the controller’s key. In the Connections pane, make sure the correct target and action pair is selected. Additional information about using controllers can be found in Cocoa Bindings Programming Topics.

---