“PredicateEditorSample” is a Cocoa application that demonstrates how to use the NSPredicateEditor class. The NSPredicateEditor class is a subclass of NSRuleEditor that is specialized for editing NSPredicate objects. This sample is intended to show how to use the many different features and aspects of this control and leverages Spotlight to search your Address Book.

It shows how to manage this control inside your window along with an NSTableView, build Spotlight friendly queries based on NSPredicate and NSCompountPredicate, build search results based on NSMetadataQuery object.

Using the Sample

Simply build the example using the supplied file. Enter query information pertaining to your Address Book. The application will display matches in its table view.

Note that this sample uses Interface Builder 3.0 to build the NSPredicateEditorRowTemplates that make up the control’s interface.

AddressBook searches are achieved by specifically requesting the “kind” of data to search via the kMDItemKind key constant. This is the metadata attribute key that tells Spotlight to search for address book data only. Together along with the other predicates from the NSPredicateEditor class we form a “compound predicate” and start the query. The code snippet below found in this sample shows how this is done:

# always search for items in the Address Book
addrBookPredicate = NSPredicate.predicateWithFormat_("(kMDItemKind = 'Address Book Person Data')")
predicate = NSCompoundPredicate.andPredicateWithSubpredicates_([addrBookPredicate, predicate])



import Cocoa
from objc import super

class CaseInsensitivePredicateTemplate (Cocoa.NSPredicateEditorRowTemplate):
    def predicateWithSubpredicates_(self, subpredicates):
        # we only make NSComparisonPredicates
        predicate = super(CaseInsensitivePredicateTemplate, self).predicateWithSubpredicates_(subpredicates)

        # construct an identical predicate, but add the
        # NSCaseInsensitivePredicateOption flag
        return Cocoa.NSComparisonPredicate.predicateWithLeftExpression_rightExpression_modifier_type_options_(
                    predicate.options() | Cocoa.NSCaseInsensitivePredicateOption)

import Cocoa
import objc

import math

searchIndex = 0

class MyWindowController (Cocoa.NSWindowController):
    query = objc.ivar()
    previousRowCount = objc.ivar(type=objc._C_INT)

    myTableView = objc.IBOutlet()
    mySearchResults = objc.IBOutlet()
    predicateEditor = objc.IBOutlet()
    progressView = objc.IBOutlet()        # the progress search view
    progressSearch = objc.IBOutlet()      # spinning gear
    progressSearchLabel = objc.IBOutlet() # search result #

    def dealloc(self):

    def awakeFromNib(self):
        # no vertical scrolling, we always want to show all rows

        self.previousRowCount = 3

        # put the focus in the first text field
        displayValue = self.predicateEditor.displayValuesForRow_(1).lastObject()
        if isinstance(displayValue,  Cocoa.NSControl):

        # create and initalize our query
        self.query = Cocoa.NSMetadataQuery.alloc().init()

        # setup our Spotlight notifications
        nf = Cocoa.NSNotificationCenter.defaultCenter()
        nf.addObserver_selector_name_object_(self, 'queryNotification:', None, self.query)

        # initialize our Spotlight query, sort by contact name

            'kMDItemContactKeywords', True)])

        # start with our progress search label empty


    def applicationShouldTerminateAfterLastWindowClosed_(self, sender):
        return True

    def loadResultsFromQuery_(self, notif):
        results = notif.object().results()

        Cocoa.NSLog("search count = %d", len(results))
        foundResultsStr = "Results found: %d"%(len(results),)

        if len(results) == 0:

        # iterate through the array of results, and match to the existing stores
        for item in results:
            cityStr = item.valueForAttribute_('kMDItemCity')
            nameStr = item.valueForAttribute_('kMDItemDisplayName')
            stateStr = item.valueForAttribute_('kMDItemStateOrProvince')
            phoneNumbers = item.valueForAttribute_('kMDItemPhoneNumbers')
            phoneStr = None
            if phoneNumbers:
                phoneStr = phoneNumbers[0]

            storePath = item.valueForAttribute_('kMDItemPath').stringByResolvingSymlinksInPath()

            # create a dictionary entry to be added to our search results array
            emptyStr = ""
            dict = {
                    'name': nameStr or "",
                    'phone': phoneStr or "",
                    'city': cityStr or "",
                    'state': stateStr or "",
                    'url': Cocoa.NSURL.fileURLWithPath_(storePath),

    def queryNotification_(self, note):
        # the NSMetadataQuery will send back a note when updates are happening.
        # By looking at the [note name], we can tell what is happening
        if == Cocoa.NSMetadataQueryDidStartGatheringNotification:
            # the query has just started
            Cocoa.NSLog("search: started gathering")


        elif == Cocoa.NSMetadataQueryDidFinishGatheringNotification:
            # at this point, the query will be done. You may recieve an update
            # later on.
            Cocoa.NSLog("search: finished gathering");



        elif == Cocoa.NSMetadataQueryGatheringProgressNotification:
            # the query is still gathering results...
            Cocoa.NSLog("search: progressing...")


        elif == Cocoa.NSMetadataQueryDidUpdateNotification:
            # an update will happen when Spotlight notices that a file as
            # added, removed, or modified that affected the search results.
            Cocoa.NSLog("search: an update happened.")

    # -------------------------------------------------------------------------
    #   inspect:selectedObjects
    #   This method obtains the selected object (in our case for single selection,
    #   it's the first item), and opens its URL.
    # -------------------------------------------------------------------------
    def inspect_(self, selectedObjects):
        objectDict = selectedObjects[0]
        if objectDict is not None:
            url = objectDict['url']

    # ------------------------------------------------------------------------
    #   spotlightFriendlyPredicate:predicate
    #   This method will "clean up" an NSPredicate to make it ready for Spotlight, or return nil if the predicate can't be cleaned.
    #   Foundation's Spotlight support in NSMetdataQuery places the following requirements on an NSPredicate:
    #           - Value-type (always YES or NO) predicates are not allowed
    #           - Any compound predicate (other than NOT) must have at least two subpredicates
    # -------------------------------------------------------------------------
    def spotlightFriendlyPredicate_(self, predicate):
        if predicate == Cocoa.NSPredicate.predicateWithValue_(True) or predicate == Cocoa.NSPredicate.predicateWithValue_(False):
            return False

        elif isinstance(predicate, Cocoa.NSCompoundPredicate):

            type = predicate.compoundPredicateType()
            cleanSubpredicates = []
            for dirtySubpredicate in predicate.subpredicates():
                cleanSubpredicate = self.spotlightFriendlyPredicate_(
                if cleanSubpredicate:

            if len(cleanSubpredicates) == 0:
                return None

                if len(cleanSubpredicates) == 1 and type != Cocoa.NSNotPredicateType:
                    return cleanSubpredicates[0]

                    return Cocoa.NSCompoundPredicate.alloc().initWithType_subpredicates_(type, cleanSubpredicates)

            return predicate

    # -------------------------------------------------------------------------
    #   createNewSearchForPredicate:predicate:withTitle
    # -------------------------------------------------------------------------
    def createNewSearchForPredicate_withTitle_(self, predicate, title):
        if predicate is not None:
                self.mySearchResults.arrangedObjects());        # remove the old search results

            # always search for items in the Address Book
            addrBookPredicate = Cocoa.NSPredicate.predicateWithFormat_(
                "(kMDItemKind = 'Address Book Person Data')")
            predicate = Cocoa.NSCompoundPredicate.andPredicateWithSubpredicates_(
                [addrBookPredicate, predicate])


    # --------------------------------------------------------------------------
    #   predicateEditorChanged:sender
    #  This method gets called whenever the predicate editor changes.
    #   It is the action of our predicate editor and the single plate for all our updates.
    #   We need to do potentially three things:
    #           1) Fire off a search if the user hits enter.
    #           2) Add some rows if the user deleted all of them, so the user isn't left without any rows.
    #           3) Resize the window if the number of rows changed (the user hit + or -).
    # --------------------------------------------------------------------------
    def predicateEditorChanged_(self, sender):
        # check NSApp currentEvent for the return key
        event = Cocoa.NSApp.currentEvent()
        if event is None:

        if event.type() == Cocoa.NSKeyDown:
            characters = event.characters()
            if len(characters) > 0 and characters[0] == u'\r':
                # get the predicat, which is the object value of our view
                predicate = self.predicateEditor.objectValue()

                # make it Spotlight friendly
                predicate = self.spotlightFriendlyPredicate_(predicate)
                if predicate is not None:
                    global searchIndex
                    title = Cocoa.NSLocalizedString("Search #%ld", "Search title");
                            predicate, title % searchIndex)
                    searchIndex += 1

        # if the user deleted the first row, then add it again - no sense leaving the user with no rows
        if self.predicateEditor.numberOfRows() == 0:

        # resize the window vertically to accomodate our views:

        # get the new number of rows, which tells us the needed change in height,
        # note that we can't just get the view frame, because it's currently animating - this method is called before the animation is finished.
        newRowCount = self.predicateEditor.numberOfRows()

        # if there's no change in row count, there's no need to resize anything
        if newRowCount == self.previousRowCount:

        # The autoresizing masks, by default, allows the NSTableView to grow and keeps the predicate editor fixed.
        # We need to temporarily grow the predicate editor, and keep the NSTableView fixed, so we have to change the autoresizing masks.
        # Save off the old ones; we'll restore them after changing the window frame.
        tableScrollView = self.myTableView.enclosingScrollView()
        oldOutlineViewMask = tableScrollView.autoresizingMask()

        predicateEditorScrollView = self.predicateEditor.enclosingScrollView()
        oldPredicateEditorViewMask = predicateEditorScrollView.autoresizingMask()

                Cocoa.NSViewWidthSizable | Cocoa.NSViewMaxYMargin)
                Cocoa.NSViewWidthSizable | Cocoa.NSViewHeightSizable)

        # determine if we need to grow or shrink the window
        growing = (newRowCount > self.previousRowCount)

        # if growing, figure out by how much.  Sizes must contain nonnegative values, which is why we avoid negative floats here.
        heightDifference = abs(self.predicateEditor.rowHeight() * (newRowCount - self.previousRowCount))

        # convert the size to window coordinates -
        # if we didn't do this, we would break under scale factors other than 1.
        # We don't care about the horizontal dimension, so leave that as 0.
        sizeChange = self.predicateEditor.convertSize_toView_(
                Cocoa.NSMakeSize(0, heightDifference), None)

        # offset our status view
        frame = self.progressView.frame()
            frame.origin.y - self.predicateEditor.rowHeight() * (newRowCount - self.previousRowCount)))

        # change the window frame size:
        # - if we're growing, the height goes up and the origin goes down (corresponding to growing down).
        # - if we're shrinking, the height goes down and the origin goes up.
        windowFrame = self.window().frame()
        if growing:
            windowFrame.size.height += sizeChange.height
            windowFrame.origin.y -= sizeChange.height
            windowFrame.size.height -= sizeChange.height
            windowFrame.origin.y += sizeChange.height

        self.window().setFrame_display_animate_(windowFrame, True, True)

        # restore the autoresizing mask

        self.previousRowCount = newRowCount     # save our new row count

from PyObjCTools import AppHelper

import CaseInsensitivePredicateTemplate
import MyWindowController


Script for building the example.

    python3 py2app
from setuptools import setup