NSUserInterfaceItemSearchDataSource Protocol Reference
| Framework | /System/Library/Frameworks/AppKit.framework |
| Declared in | AppKit/NSUserInterfaceItemSearchDataSource.h |
| Companion guide |
Overview
Spotlight For Help provides a mechanism to index and search graphical user Interfaces that consist of hierarchies of objects including but not limited to Menus, Windows, Views, Controls, and Accessibility Attributes.
To enable Spotlight For Help to find UI elements not in menus, Spotlight For Help provides an extension mechanism in the form of a protocol that allows developers to locate these additional UI elements and provide them to Spotlight For Help.
The following Application Kit function adds a search data source to Spotlight For Help:
extern void NSRegisterSearchDataSource(id<NSUserInterfaceItemSearchDataSource> dataSource); |
The following Application Kit function removes a search data source from Spotlight For Help:
extern void NSUnregisterSearchDataSource(id<NSUserInterfaceItemSearchDataSource> dataSource); |
For descriptions of these and other Application Kit functions that you can use with Spotlight For Help, see Application Kit Functions Reference.
Instance Methods
hideContainerForItem
Called when Spotlight for Help wants to dismiss the window or panel that contains the item.
Parameters
- item
The UI item revealed by Spotlight For Help in response to a search string.
Discussion
Implementation of this method is optional.
hideItem:
Called when Spotlight For Help wants to hide a previously shown item.
Parameters
- item
The UI item revealed by Spotlight For Help in response to a search string.
Discussion
Implementation of this method is optional.
iconForItem:
Returns a custom icon to display in the menu for this item.
Parameters
- item
The UI item revealed by Spotlight For Help in response to a search string.
Return Value
A custom icon to display when this item is returned in the Help menu.
Discussion
Implementation of this method is optional.
itemIsVisible:
Called as needed to verify that an item is visible on the screen.
Parameters
- item
The UI item revealed by Spotlight For Help in response to a search string.
Return Value
YES if the item is still visible.
Discussion
Spotlight For Help calls this method to verify that it should continue to show the pointer. Implementation of this method is optional.
itemsForSearchString:withPartialResults:
Returns a list of items for the search string. (required)
Parameters
- searchString
The search string that the user entered in the Search text field.
- partialResults
On output, set this parameter to
YESif the results returned are only partial and Spotlight for Help should call this method again for more results. In this case it is your responsibility to remember the previous search string, return additional results if the search string is the same as the last time, or initiate a new search if the string has changed.
Return Value
An array of identifiers for the user interface items that relate to the search string.
Discussion
The identifiers are not interpreted by Spotlight For Help; they are used only to identify particular search results for the other Spotlight For Help methods. You are responsible for maintaining the mapping of these identifiers to the search result items.
This method may be called from a thread other than the main UI thread.
performActionForItem:
Called when Spotlight For Help wants to perform the action associated with this UI item.
Parameters
- item
The UI item revealed by Spotlight For Help in response to a search string.
Discussion
When the user chooses an item in Spotlight For Help menu and clicks the mouse or presses Enter or Return, you can perform the operation normally invoked by the user clicking on the item in your UI. Implementation of this method is optional.
screenRectForItem:
Returns the boundaries of the UI element (required)
Parameters
- item
The UI item revealed by Spotlight For Help in response to a search string.
Return Value
A rectangle (NSRect) in screen coordinates of the boundary of the UI element.
Discussion
Spotlight For Help uses the rectangle you return to determine where to locate the floating pointer that highlights the UI element for the user. This method is called only after the showItem: method has been called.
showItem:
Called when Spotlight For Help needs to show the UI element associated with this search result. (required)
Parameters
- item
The UI item revealed by Spotlight For Help in response to a search string.
Discussion
When Spotlight For Help calls this method, you should show the specified UI element. For example, if the user selects an item in the Preferences dialog, you should display the relevant tab of the Preferences dialog when Spotlight For Help calls this method.
titlesForItem:
Returns an array of localized strings that will be used to form the menu item title. (required)
Parameters
- item
The UI item revealed by Spotlight For Help in response to a search string.
Discussion
The menu item title should indicate the entire hierarchy of the UI element being returned; for example Preferences > Plain Text Font. The angle-bracket seperators are provided by Spotlight For Help—you need to provide an array of strings for the elements in the hierarchy; for example, [NSArray, arrayWithObjects:"Preferences","Plain Text Font",nil].
© 2013 Apple Inc. All Rights Reserved. (Last updated: 2013-01-28)