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 AppKit Functions Reference.

Tasks

Adding Items to the Spotlight For Help Menu

Showing UI Elements

Invoking a UI Element

Instance Methods

hideContainerForItem

Called when Spotlight for Help wants to dismiss the window or panel that contains the item.

- (void)hideContainerForItem:(id)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.

- (void)hideItem:(id)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.

- (NSImage*)iconForItem:(id)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.

- (void)itemIsVisible:(id)item;
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)

- (NSArray*)itemsForSearchString:(NSString*)searchString withPartialResults:(BOOL*)partialResults;
Parameters
searchString

The search string that the user entered in the Search text field.

partialResults

On output, set this parameter to YES if 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.

- (void)performActionForItem:(id)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)

- (NSRect)screenRectForItem:(id)item;
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)

- (void)showItem:(id)item;
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)

- (NSArray*)titlesForItem:(id)item;
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].