Mac Developer Library

Developer

AppKit Framework Reference NSUserInterfaceItemSearchDataSource Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSUserInterfaceItemSearchDataSource

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

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable Not Applicable
  • Returns a list of items for the search string. (required)

    Declaration

    Objective-C

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

    Import Statement

  • Returns an array of localized strings that will be used to form the menu item title. (required)

    Declaration

    Objective-C

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

    Import Statement

  • Returns a custom icon to display in the menu for this item.

    Declaration

    Objective-C

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

    Import Statement

  • showItem: showItem: Required

    Called when Spotlight For Help needs to show the UI element associated with this search result. (required)

    Declaration

    Objective-C

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

    Import Statement

  • Returns the boundaries of the UI element (required)

    Declaration

    Objective-C

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

    Import Statement

  • Called as needed to verify that an item is visible on the screen.

    Declaration

    Objective-C

    - (void)itemIsVisible:(id)item;

    Parameters

    item

    The UI item revealed by Spotlight For Help in response to a search string.

    Return Value

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

    Import Statement

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

    Declaration

    Objective-C

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

    Import Statement

  • Called when Spotlight For Help wants to hide a previously shown item.

    Declaration

    Objective-C

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

    Import Statement

  • Called when Spotlight For Help wants to perform the action associated with this UI item.

    Declaration

    Objective-C

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

    Import Statement