Mac Developer Library

Developer

AppKit Framework Reference NSSearchFieldCell Class Reference

Options
Deployment Target:

On This Page
Language:

NSSearchFieldCell

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 in NSSearchField Class Reference 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. More...

Inheritance


Import Statement


import AppKit @import AppKit;

Availability


Available in OS X v10.3 and later.
  • Sets the button cell used to display the search-button image

    Declaration

    Swift

    var searchButtonCell: NSButtonCell?

    Objective-C

    @property(strong) NSButtonCell *searchButtonCell

    Parameters

    cell

    The search button cell.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    var searchButtonCell: NSButtonCell?

    Objective-C

    @property(strong) NSButtonCell *searchButtonCell

    Return Value

    The search button cell.

    Import Statement

    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. 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

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Sets the button cell object used to display the cancel-button image

    Declaration

    Swift

    var cancelButtonCell: NSButtonCell?

    Objective-C

    @property(strong) NSButtonCell *cancelButtonCell

    Parameters

    cell

    The cancel button cell.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns the button cell object used to display the cancel-button image.

    Declaration

    Swift

    var cancelButtonCell: NSButtonCell?

    Objective-C

    @property(strong) NSButtonCell *cancelButtonCell

    Return Value

    The cancel button cell.

    Import Statement

    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. 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

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • 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

    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

    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

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Sets the menu template object used to dynamically construct the receiver's pop-up icon menu.

    Declaration

    Swift

    var searchMenuTemplate: NSMenu?

    Objective-C

    @property(strong) NSMenu *searchMenuTemplate

    Parameters

    menu

    The menu template to use.

    Discussion

    The receiver looks for the tag constants described in “Menu tags” to determine how to populate the menu with items related to recent searches. See Configuring a Search Menu in Search Fields for a sample of how you might set up the search menu template.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns the menu template object used to dynamically construct the search pop-up icon menu.

    Declaration

    Swift

    var searchMenuTemplate: NSMenu?

    Objective-C

    @property(strong) NSMenu *searchMenuTemplate

    Return Value

    The current menu template.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Sets whether the receiver sends the search action message when the user clicks the search button (or presses return) or after each keystroke.

    Declaration

    Swift

    var sendsWholeSearchString: Bool

    Objective-C

    @property BOOL sendsWholeSearchString

    Parameters

    flag

    YEStrue to send the action message all at once when the user clicks the search button or presses return; otherwise, NOfalse to send the search string after each keystroke.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns a Boolean value indicating whether the receiver sends the search action message when the user clicks the search button (or presses return) or after each keystroke.

    Declaration

    Swift

    var sendsWholeSearchString: Bool

    Objective-C

    @property BOOL sendsWholeSearchString

    Return Value

    YEStrue if the action message is sent all at once when the user clicks the search button or presses return; otherwise, NOfalse if the search string is sent after each keystroke. The default value is NOfalse.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns a Boolean value indicating whether the receiver sends its action immediately upon being notified of changes to the search field text or after a brief pause.

    Declaration

    Swift

    var sendsSearchStringImmediately: Bool

    Objective-C

    @property BOOL sendsSearchStringImmediately

    Return Value

    YEStrue if the cell sends its action immediately upon notification of any changes to the search field; otherwise, NOfalse.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets whether the cell sends its action message to the target immediately upon notification of any changes to the search field text or after a brief pause.

    Declaration

    Swift

    var sendsSearchStringImmediately: Bool

    Objective-C

    @property BOOL sendsSearchStringImmediately

    Parameters

    flag

    YEStrue to send the cell's action immediately upon notification of any changes to the search field; otherwise, NOfalse if you want the cell to pause briefly before sending its action message. Pausing gives the user the opportunity to type more text into the search field before initiating the search.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    var maximumRecents: Int

    Objective-C

    @property NSInteger maximumRecents

    Parameters

    maxRecents

    The maximum number of search strings that can appear in the menu. This value can be between 0 and 254. Specifying a value less than 0 sets the value to the default, which is 10. Specifying a value greater than 254 sets the maximum to 254.

    Discussion

    When the limit is exceeded, the oldest search string on the menu is dropped.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns the maximum number of recent search strings to display in the custom search menu.

    Declaration

    Swift

    var maximumRecents: Int

    Objective-C

    @property NSInteger maximumRecents

    Return Value

    The maximum number of search strings that can appear in the menu. This value is between 0 and 254.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Sets the list of recent search strings to list in the pop-up icon menu of the receiver.

    Declaration

    Swift

    var recentSearches: [AnyObject]!

    Objective-C

    @property(copy) NSArray *recentSearches

    Parameters

    searches

    An array of NSString objects containing the search strings.

    Discussion

    You might use this method to set the recent list of searches from an archived copy.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns the list of recent search strings for the control.

    Declaration

    Swift

    var recentSearches: [AnyObject]!

    Objective-C

    @property(copy) NSArray *recentSearches

    Return Value

    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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Sets the autosave name under which the receiver automatically archives the list of recent search strings.

    Declaration

    Swift

    var recentsAutosaveName: String?

    Objective-C

    @property(copy) NSString *recentsAutosaveName

    Parameters

    name

    The autosave name, which 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 autosaved.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns the key under which the prior list of recent search strings has been archived.

    Declaration

    Swift

    var recentsAutosaveName: String?

    Objective-C

    @property(copy) NSString *recentsAutosaveName

    Return Value

    The autosave name, which is used as a key in the standard user defaults to save the recent searches. The default value is nil, which causes searches not to be autosaved.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • The NSSearchFieldCell class uses these tag constants for identifying special menu items in the search-menu template set by setSearchMenuTemplate:. When an NSSearchFieldCell object dynamically constructs the actual search menu from this template, it shows or hides the tagged items as directed.

    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.

    Import Statement