Mac Developer Library

Developer

AppKit Framework Reference NSUserInterfaceItemSearching Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSUserInterfaceItemSearching

The NSUserInterfaceItemSearching protocol show an application can implement Spotlight for Help for their own custom help data.

In general, users find the Help search functionality very useful. However, many large applications don't use Apple Help API because of cross platform requirements. Hence, important Help topics are not presented as part of the Help menu. This API allows developers to incorporate their own Help topics and take full advantage of the Help feature.

In your application you implement the NSUserInterfaceItemSearching protocol and then register your object with registerUserInterfaceItemSearchHandler:.

Inheritance


Not Applicable

Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.6 and later.
  • Returns an array of localized strings that will form the help menu item. (required)

    Declaration

    Swift

    func localizedTitlesForItem(_ item: AnyObject) -> [AnyObject]

    Objective-C

    - (NSArray *)localizedTitlesForItem:(id)item

    Parameters

    item

    At item in the help menu.

    Return Value

    An NSArray of NSStrings (localized for display in the menu) that will be combined with separators to form the menu item title.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • If this method is implemented, a "Show All Help Topics" item will appear in the menu and this method is called when the user selects it.

    Declaration

    Swift

    optional func showAllHelpTopicsForSearchString(_ searchString: String)

    Objective-C

    - (void)showAllHelpTopicsForSearchString:(NSString *)searchString

    Parameters

    searchString

    The search string.

    Discussion

    The application should show all its results for this search, which does not include results for menu items. The string for "Show All Help Topics" is system defined and localized and cannot be changed by the user.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Search for the specified items, with the result limit. (required)

    Declaration

    Swift

    func searchForItemsWithSearchString(_ searchString: String, resultLimit resultLimit: Int, matchedItemHandler handleMatchedItems: ([AnyObject]!) -> Void)

    Objective-C

    - (void)searchForItemsWithSearchString:(NSString *)searchString resultLimit:(NSInteger)resultLimit matchedItemHandler:(void (^)(NSArray *items))handleMatchedItems

    Parameters

    searchString

    The string to search for.

    resultLimit

    The maximum number of results that Spotlight for Help will process. Any results returned beyond this limit will be ignored, but for performance reasons it is better to not exceed it.

    handleMatchedItems

    The Block used to add results to the search.

    The Block takes one argument:

    items

    The items to add to the results array. The handleMatchedItems block can be invoked from any thread desired. If it is called more than once the additional results will be appended after previous items until the maximum is reached.

    Discussion

    Search for items matching the provided search string and return them by calling the matched items block, passing an array of items to append to the help menu. The framework does not care what these items are. They are just used to identify particular search results to other methods in this protocol. Do not assume that this will be called from the main UI thread.

    When searchForItemsWithSearchString:resultLimit:matchedItemHandler: gets called again, the client should cancel any previous searches in progress for better performance. If not Spotlight for Help will ignore the older results.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Invoked when the user selects a search result in Help menu.

    Declaration

    Swift

    optional func performActionForItem(_ item: AnyObject)

    Objective-C

    - (void)performActionForItem:(id)item

    Parameters

    item

    An item in the help menu.

    Discussion

    The default implementation brings up Help Viewer for a Help item.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.