Configuring a Search Menu

A search field has a menu that users can access by clicking the small triangle next to the search button. The items in this pop-up icon menu have two purposes: To list recently entered search strings, and to list search categories for limiting the scope of the search. You can also specify when the search field sends its action message.

Generating Action Messages

A search field has two modes for generating action messages. The first mode is similar to a text field; a message is sent when a user clicks the search button or presses Return when the insertion point is in the search field. The second mode, which is the default, is for incremental searches; the search field sends an action message at each keystroke. Typically you set the mode in Interface Builder (see ‚ÄúAdding a Search Field to Your Application‚Äù). To set the message-generation mode programmatically, send setSendsWholeSearchString: to the search field cell with an argument of NO for incremental searches and YES for regular searches.

Configuring a Menu Template

If you specify a menu in Interface Builder or programatically, the search button has a menu indicator and the search menu is displayed when the user clicks the search button. Do not modify the menu while it is in use by the search field. This is because a copy is not made.

To configure this pop-up menu, create a menu template (which is an NSMenu object) and populate this menu template with the items (NSMenuItem objects) you want to appear. Items in the menu can be given special meaning by using predefined tags described in the Constants section of NSSearchFieldCell.

You can specify the menu template used when generating the pop-up menu in the search field. This is easily done with Interface Builder. Or, if you have programmatically constructed the menu template, invoke setSearchMenuTemplate: to install it in the search field.

Figure 1 shows a simple menu template with a recents item, a clear item, and a no recents item.

Figure 1  Sample menu template with info pane

The menu item tag is specified in the Tag field. In Figure 1, the menu item is of the type NSSearchFieldRecentsMenuItemTag. Although not pictured, the tag for the Clear menu item is NSSearchFieldClearRecentsMenuItemTag and for the Empty menu item it‚Äôs NSSearchFieldNoRecentsMenuItemTag. You can also add a menu item with the NSSearchFieldRecentsTitleMenuItemTag tag for an item that does not appear if there are no recent strings to display, or conversely a menu item with the NSSearchFieldNoRecentsMenuItemTag tag for an item that only appears if there are no recent strings to display.

You can also do all of this programatically. Listing 1 illustrates how you might set up the search menu template.

Listing 1  Setting the menu template for recent search strings

- (void) awakeFromNib

{

    NSMenu *cellMenu = [[[NSMenu alloc] initWithTitle:@"Search Menu"]

                autorelease];

    NSMenuItem *item;

    item = [[[NSMenuItem alloc] initWithTitle:@"Clear"

                                action:NULL

                                keyEquivalent:@""] autorelease];

    [item setTag:NSSearchFieldClearRecentsMenuItemTag];

    [cellMenu insertItem:item atIndex:0];

    item = [NSMenuItem separatorItem];

    [item setTag:NSSearchFieldRecentsTitleMenuItemTag];

    [cellMenu insertItem:item atIndex:1];

    item = [[[NSMenuItem alloc] initWithTitle:@"Recent Searches"

                                action:NULL

                                keyEquivalent:@""] autorelease];

    [item setTag:NSSearchFieldRecentsTitleMenuItemTag];

    [cellMenu insertItem:item atIndex:2];

    item = [[[NSMenuItem alloc] initWithTitle:@"Recents"

                                action:NULL

                                keyEquivalent:@""] autorelease];

    [item setTag:NSSearchFieldRecentsMenuItemTag];

    [cellMenu insertItem:item atIndex:3];

    id searchCell = [searchField cell];

    [searchCell setSearchMenuTemplate:cellMenu];

}

A menu is associated with your search field only if you specify one with Interface Builder. If you are creating the search field programatically and do not want a menu, set the menu template to nil.

Specifying a Search Category

To set up a search category, you create a menu item with a title and an action selector and add it to the menu template. The action selector identifies the method that is invoked using the target-action paradigm when the user selects the item; in this method you can set a flag or other value so that your search implementation knows how to limit the scope of its search. Typically you would add the menu item to the menu template in Interface Builder. You can also do it programmatically, as illustrated in Listing 2. This is useful if you create or update the menu dynamically, for example if the categories depend on what table columns are visible in a table view.

Listing 2  Setting the menu template with a search category

- (void) awakeFromNib

{

    NSMenu *cellMenu = [[[NSMenu alloc] initWithTitle:@"Search Menu"]

                        autorelease];

    NSMenuItem *item;

    item = [[[NSMenuItem alloc] initWithTitle:@"First Name"

                                       action:@selector(setSearchCategoryFrom:)

                                keyEquivalent:@""] autorelease];

    [item setTarget:self];

    [item setTag:1];

    [cellMenu insertItem:item atIndex:0];

    item = [[[NSMenuItem alloc] initWithTitle:@"Last Name"

                                       action:@selector(setSearchCategoryFrom:)

                                keyEquivalent:@""] autorelease];

    [item setTarget:self];

    [item setTag:2];

    [cellMenu insertItem:item atIndex:1];

    id searchCell = [searchField cell];

    [searchCell setSearchMenuTemplate:cellMenu];

}

Tags are optional for search categories, but they allow you to easily discriminate between menu items in the action method. If you choose to specify tags, their values must not be any of the values corresponding to NSSearchFieldRecentsTitleMenuItemTag, NSSearchFieldRecentsMenuItemTag, NSSearchFieldClearRecentsMenuItemTag, or NSSearchFieldNoRecentsMenuItemTag.

You also have to implement the action method invoked by the menu item—see “Search Using a Search Category.”