NSUserInterfaceItemSearching Protocol Reference

Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.6 and later.
Declared in
NSUserInterfaceItemSearching.h

Overview

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

Tasks

Show Help Menu

Search Help Content

Instance Methods

localizedTitlesForItem:

Returns an array of localized strings that will form the help menu item. (required)

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

Availability
  • Available in OS X v10.6 and later.
Declared In
NSUserInterfaceItemSearching.h

performActionForItem:

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

- (void)performActionForItem:(id)item
Parameters
item

An item in the help menu.

Discussion

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

Availability
  • Available in OS X v10.6 and later.
Declared In
NSUserInterfaceItemSearching.h

searchForItemsWithSearchString:resultLimit:matchedItemHandler:

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

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

Availability
  • Available in OS X v10.6 and later.
Declared In
NSUserInterfaceItemSearching.h

showAllHelpTopicsForSearchString:

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.

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

Availability
  • Available in OS X v10.6 and later.
Declared In
NSUserInterfaceItemSearching.h