Mac Developer Library

Developer

AppKit Framework Reference NSSearchFieldCell Class Reference

Options
Deployment Target:

On This Page
Language:

NSSearchFieldCell

Inheritance


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.3 and later.

The NSSearchFieldCell class defines the programmatic interface for text fields that are optimized for text-based searches. An NSSearchFieldCell object is “wrapped” by an NSSearchField control object, which directly inherits from the NSTextField class. The search field implemented by these classes presents a standard user interface for searches, including a search button, a cancel button, and a pop-up icon menu for listing recent search strings and custom search categories.

When the user types and then pauses, the cell’s action message is sent to its target. You can query the cell’s string value for the current text to search for. Do not rely on the sender of the action to be an NSMenu object because the menu may change. If you need to change the menu, modify the search menu template and update the value in the searchMenuTemplate property.

  • The button cell used to display the search-button image.

    Declaration

    Swift

    var searchButtonCell: NSButtonCell?

    Objective-C

    @property(strong) NSButtonCell *searchButtonCell

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Resets the search button cell to its default attributes.

    Declaration

    Swift

    func resetSearchButtonCell()

    Objective-C

    - (void)resetSearchButtonCell

    Discussion

    This method resets the target, action, regular image, and pressed image for the search button cell. By default, when users click the search button or press the Return key, the action defined for the receiver is sent to its designated target. This method gives you a way to customize the search button for specific situations and then reset the button defaults without having to undo changes individually.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

    See Also

    searchButtonCell

  • The button cell used to display the cancel-button image.

    Declaration

    Swift

    var cancelButtonCell: NSButtonCell?

    Objective-C

    @property(strong) NSButtonCell *cancelButtonCell

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Resets the cancel button cell to its default attributes.

    Declaration

    Swift

    func resetCancelButtonCell()

    Objective-C

    - (void)resetCancelButtonCell

    Discussion

    This method resets the target, action, regular image, and pressed image for the cancel button cell. By default, when users click the cancel button, the delete: action message is sent up the responder chain to the first NSText object that can handle it. This method gives you a way to customize the cancel button for specific situations and then reset the button defaults without having to undo changes individually.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

    See Also

    cancelButtonCell

  • Modifies the bounding rectangle for the search-text field cell.

    Declaration

    Swift

    func searchTextRectForBounds(_ rect: NSRect) -> NSRect

    Objective-C

    - (NSRect)searchTextRectForBounds:(NSRect)rect

    Parameters

    rect

    The current bounding rectangle for the search text field.

    Return Value

    The updated bounding rectangle to use for the search text field. The default value is the value passed into the rect parameter.

    Discussion

    Subclasses can override this method to return a new bounding rectangle for the text-field cell object. You might use this method to provide a custom layout for the search field control.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Modifies the bounding rectangle for the search button cell.

    Declaration

    Swift

    func searchButtonRectForBounds(_ rect: NSRect) -> NSRect

    Objective-C

    - (NSRect)searchButtonRectForBounds:(NSRect)rect

    Parameters

    rect

    The current bounding rectangle for the search button.

    Return Value

    The updated bounding rectangle to use for the search button. The default value is the value passed into the rect parameter.

    Discussion

    Subclasses can override this method to return a new bounding rectangle for the search button cell. You might use this method to provide a custom layout for the search field control.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Modifies the bounding rectangle for the cancel button cell.

    Declaration

    Swift

    func cancelButtonRectForBounds(_ rect: NSRect) -> NSRect

    Objective-C

    - (NSRect)cancelButtonRectForBounds:(NSRect)rect

    Parameters

    rect

    The current bounding rectangle for the cancel button.

    Return Value

    The updated bounding rectangle to use for the cancel button. The default value is the value passed into the rect parameter.

    Discussion

    Subclasses can override this method to return a new bounding rectangle for the cancel button cell. You might use this method to provide a custom layout for the search field control.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • The menu object used to dynamically construct the search field’s pop-up icon menu.

    Declaration

    Swift

    var searchMenuTemplate: NSMenu?

    Objective-C

    @property(strong) NSMenu *searchMenuTemplate

    Discussion

    The cell looks for the tag constants described in Menu tags to determine how to populate the menu with items related to recent searches. For an example of how you might set up the search menu template, see Configuring a Search Menu.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • A Boolean value indicating whether the cell calls its search action method when the user clicks the search button (or presses Return) or after each keystroke.

    Declaration

    Swift

    var sendsWholeSearchString: Bool

    Objective-C

    @property BOOL sendsWholeSearchString

    Discussion

    When the value of this property is YEStrue, the cell calls its action method when the user clicks the search button or presses Return. When the value is NOfalse, the cell calls the action method after each keystroke. The default value of this property is NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • A Boolean value indicating whether the cell calls its action method immediately when an appropriate action occurs.

    Declaration

    Swift

    var sendsSearchStringImmediately: Bool

    Objective-C

    @property BOOL sendsSearchStringImmediately

    Discussion

    When the value of this property is YEStrue, the cell calls its action method immediately upon notification of any changes to the search field. When the value is NOfalse, the cell pauses briefly after receiving a notification and then calls its action method. Pausing gives the user an opportunity to type more text into the search field and minimize the number of searches that are performed.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • The maximum number of search strings that can appear in the search menu.

    Declaration

    Swift

    var maximumRecents: Int

    Objective-C

    @property NSInteger maximumRecents

    Discussion

    The value of this property must be between 0 and 254. Specifying a negative value for the property sets it to the default value, which is 10. Specifying a value greater than 254 sets the property to 254.

    When the maximum number of search strings is exceeded, the oldest search string on the menu is dropped.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • An array of the recent search strings to display in the pop-up icon menu of the search field.

    Declaration

    Swift

    var recentSearches: [AnyObject]!

    Objective-C

    @property(copy) NSArray *recentSearches

    Discussion

    This property contains an array of NSString objects, each of which contains a search string either displayed in the search menu or from a recent autosave archive. If there have been no recent searches and no prior searches saved under an autosave name, this array may be empty. When loading your interface, you might set the value of this property to a set of saved search strings.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • The autosave name under which the search field automatically saves the list of recent search strings.

    Declaration

    Swift

    var recentsAutosaveName: String?

    Objective-C

    @property(copy) NSString *recentsAutosaveName

    Discussion

    The autosave name is used as a key in the standard user defaults to save the recent searches. If you specify nil or an empty string for this parameter, no autosave name is set and searches are not automatically saved.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

    See Also

    recentSearches

  • Constants for identifying special menu items in the search-menu template.

    Declaration

    Swift

    var NSSearchFieldRecentsTitleMenuItemTag: Int32 { get } var NSSearchFieldRecentsMenuItemTag: Int32 { get } var NSSearchFieldClearRecentsMenuItemTag: Int32 { get } var NSSearchFieldNoRecentsMenuItemTag: Int32 { get }

    Objective-C

    #define NSSearchFieldRecentsTitleMenuItemTag 1000 #define NSSearchFieldRecentsMenuItemTag 1001 #define NSSearchFieldClearRecentsMenuItemTag 1002 #define NSSearchFieldNoRecentsMenuItemTag 1003

    Constants

    • NSSearchFieldRecentsTitleMenuItemTag

      NSSearchFieldRecentsTitleMenuItemTag

      Identifies the menu item that is the title of the menu group for recent search strings.

      This item is hidden if there are no recent strings.

      You may use this tagged item for separator characters that also do not appear if there are no recent strings to display.

      Available in OS X v10.3 and later.

    • NSSearchFieldRecentsMenuItemTag

      NSSearchFieldRecentsMenuItemTag

      Identifies where recent search strings should appear in the “recents” menu group.

      Available in OS X v10.3 and later.

    • NSSearchFieldClearRecentsMenuItemTag

      NSSearchFieldClearRecentsMenuItemTag

      Identifies the menu item for clearing the current set of recent string searches in the menu.

      This item is hidden if there are no recent strings.

      Available in OS X v10.3 and later.

    • NSSearchFieldNoRecentsMenuItemTag

      NSSearchFieldNoRecentsMenuItemTag

      Identifies the menu item that describes a lack of recent search strings (for example, “No recent searches”).

      This item is hidden if there have been recent searches.

      Available in OS X v10.3 and later.

    Discussion

    When an NSSearchFieldCell object dynamically constructs the actual search menu from this template, it shows or hides the tagged items as directed.

    Availability

    Available in OS X v10.3 and later.