Class

SpotlightQuery

Description

Used to perform Spotlight searches on macOS. It does nothing on other operating systems.

Properties

Name	Type	Read-Only
Completed	Boolean	✓
Handle	Integer	✓
Query	String
Synchronous	Boolean

Methods

Name	Parameters	Returns
Constructor	query As String
Count		Integer
Item	Index As Integer	SpotlightItem
Pause
Resume
Run
Stop

Events

Name	Parameters	Returns
Changed	itemsAdded() As SpotlightItem, itemsChanged() As SpotlightItem, itemsRemoved() As SpotlightItem
Completed

Property descriptions

SpotlightQuery.Completed

Completed As Boolean

This property is read-only.

SpotlightQuery.Handle

Handle As Integer

Returns the handle to the MDQueryRef.

This property is read-only.

This can be used in Declares to access Spotlight features that are not supported directly by this class. It may not be available until after calling the Run method.

SpotlightQuery.Query

Query As String

The query string that will be passed to the Spotlight engine.

You search on the metadata attribute keys provided by Apple using their format. See the notes for the format of the query.

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()
  ListBox1.RemoveAllRows
  Query.Pause
  For i As Integer = 0 To Query.Count - 1
    ListBox1.AddRow(Query.Item(i).File.DisplayName)
    ListBox1.CellTextAt(ListBox1.LastAddedRowIndex, 1) = Query.Item(i).File.NativePath
  Next
  Query.Resume
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 Not TextField1.Text.IsEmpty Then
  Query.Query = "kMDItemDisplayName == ""*" + TextField1.Text + "*"""
  Query.Run
Else
  MessageBox("Please enter a file name to search for.")
End If

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

SpotlightQuery.Synchronous

Synchronous As Boolean

If True, the Run method will be synchronous. If it is synchronous, then the events will not fire.

This example enables the Synchronous property.

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

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

Method descriptions

SpotlightQuery.Constructor

Constructor(query As String)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Creates a SpotlightQuery object, optionally with the passed query. If not passed, it defaults to no query.

The following synchronous query populates a DesktopListBox 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 DesktopButton.

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

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

SpotlightQuery.Count

Count As Integer

Gets the number of results of the query.

The following synchronous query populates a DesktopListBox 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 DesktopButton.

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

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

SpotlightQuery.Item

Item(Index As Integer) As SpotlightItem

Returns the SpotlightItem specified by Index. Index is zero-based.

The following synchronous query populates a DesktopListBox 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 DesktopButton.

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

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

SpotlightQuery.Pause

Pause

Temporarily pauses the query from posting any updates.

This means that the Count and Item functions will not change until you resume the query by calling Resume.

SpotlightQuery.Resume

Resume

Resumes reporting more results after the query has been paused.

SpotlightQuery.Run

Run

Runs the query specified by the Query property.

The following synchronous query populates a DesktopListBox 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 DesktopButton.

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

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

SpotlightQuery.Stop

Stop

Stops the query.

Event descriptions

SpotlightQuery.Changed

Changed(itemsAdded() As SpotlightItem, itemsChanged() As SpotlightItem, itemsRemoved() As SpotlightItem)

This event is fired when the SpotlightQuery has either found more items, determined that some no longer match, or both.

When doing the initial gathering, itemsAdded() is not populated for speed reasons since it can be called frequently.

SpotlightQuery.Completed

Completed

Fired when the SpotlightQuery has finished gathering the initial items.

Call the Stop method inside this event if you would not like to know when new documents match the query. If you don't call Stop, the Changed event will fire if items no longer match or new items match the query.

Notes

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 == 'public.audio' && kMDItemArtist == "Lifehouse".

Apple provides a complete description of the MDQuery syntax.

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

Sample code

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 == 'public.audio'")
query.Synchronous = True
query.Run
For i As Integer = 0 To query.Count - 1
  ListBox1.AddRow(query.Item(i).File.DisplayName)
  ListBox1.CellTextAt(ListBox1.LastAddedRowIndex, 1) = query.Item(i).File.NativePath
Next

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()
  ListBox1.RemoveAllRows
  Query.Pause
  For i As Integer = 0 To Query.Count - 1
    ListBox1.AddRow(Query.Item(i).File.DisplayName)
    ListBox1.CellTextAt(ListBox1.LastAddedRowIndex, 1) = Query.Item(i).File.NativePath
  Next
  Query.Resume
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 Not TextField1.Text.IsEmpty Then
  Query.Query = "kMDItemDisplayName == ""*" + TextField1.Text + "*"""
  Query.Run
Else
  MessageBox("Please enter a file name to search for.")
End If

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

Compatibility

All project types on all supported operating systems.