From Xojo Documentation

You are currently browsing the old Xojo documentation site. Please visit the new Xojo documentation site!

Class (inherits from Object)

Used to perform Spotlight searches on macOS. It does nothing on other operating systems. SpotlightQuery appears in the list of Built-in controls in the IDE, but since it is not subclassed from Control, you can instantiate it via code.

Changed Completed

Completed fa-lock-32.png Query
Handle fa-lock-32.png Synchronous

Count Pause Run
Item Resume Stop


Constructor(query as String)


Apple provides an overview of Spotlight.

Spotlight works by extracting metadata attributes from files on the user's hard disk. By default, this extraction is done in the background by Spotlight Importers. When an end-user does a Spotlight search, he is actually doing a search on the attributes that have been extracted via the importers. When you use the SpotlightQuery class, you must specify the attribute or attributes you are searching on using Spotlight keywords and syntax.

In other words, you will need to become familiar with Apple's MDQuery language. Each simple query is in the format of attribute=Value, where attribute is a Spotlight metadata attribute and Value is the target value.

Apple's provides a list of searchable metadata attributes.

For example, kMDItemContentType == "*audio*" would find all files that had a content type containing "audio" (case insensitive). The "*" is the wildcard character. You can combine expressions with "&&" (logical "And") and "||" (logical "Or"). For example, to find a file that was Audio and had a artist of Lifehouse, it would look like this: kMDItemContentTree == '' && kMDItemArtist == "Lifehouse".

Apple provides a complete description of the MDQuery syntax.

See also Uniform Type Identifiers to see how to search files by type.


The following synchronous query populates a ListBox with the list of audio files on the user’s computer and the absolute path to each file. You can put the code in a Button.

Var query As New SpotlightQuery("kMDItemContentTypeTree == ''")
query.Synchronous = True
For i As Integer = 0 To query.Count - 1
ListBox1.CellTextAt(ListBox1.LastAddedRowIndex, 1) = query.Item(i).File.NativePath

Exception e As SpotlightException
MessageBox("A Spotlight error occurred.")

The following asynchronous query uses the search string that the user enters into a TextField and displays the filename and its absolute path in a Listbox. It uses a SpotlightQuery control named "Query" that has been added to the window.

First, add the following method "UpdateList" to the window:

Sub UpdateList()
For i As Integer = 0 To Query.Count - 1
ListBox1.CellTextAt(ListBox1.LastAddedRowIndex, 1) = Query.Item(i).File.NativePath
End Sub

In the SpotLightQuery's Changed and Completed event handlers, call the UpdateList method.

In a DesktopButton, enter the following code in its Pressed event handler.

If TextField1.Text <> "" Then
Query.Query = "kMDItemDisplayName == ""*" + TextField1.Text + "*"""
MessageBox("Please enter a file name to search for.")
End If

Exception e As SpotlightException
MessageBox("A Spotlight error occurred.")

See Also

SpotlightException, SpotlightItem classes.