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
-
– localizedTitlesForItem:required method -
– showAllHelpTopicsForSearchString:
Search Help Content
Instance Methods
localizedTitlesForItem:
Returns an array of localized strings that will form the help menu item. (required)
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.hperformActionForItem:
Invoked when the user selects a search result in Help menu.
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.hsearchForItemsWithSearchString:resultLimit:matchedItemHandler:
Search for the specified items, with the result limit. (required)
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.hshowAllHelpTopicsForSearchString:
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.
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© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-08-20)