docs » hs.spotlight.group

This sub-module is used to access results to a spotlightObject query which have been grouped by one or more attribute values.

A spotlightGroupObject is a special object created when you specify one or more grouping attributes with hs.spotlight:groupingAttributes. Spotlight items which match the Spotlight query and share a common value for the specified attribute will be grouped in objects you can retrieve with the hs.spotlight:groupedResults method. This method returns an array of spotlightGroupObjects.

For each spotlightGroupObject you can identify the attribute and value the grouping represents with the hs.spotlight.group:attribute and hs.spotlight.group:value methods. An array of the results which belong to the group can be retrieved with the hs.spotlight.group:resultAtIndex method. For convenience, metamethods have been added to the spotlightGroupObject which make accessing individual results easier: an individual spotlightItemObject may be accessed from a spotlightGroupObject by treating the spotlightGroupObject like an array; e.g. spotlightGroupObject[n] will access the n'th spotlightItemObject in the grouped results.

API Overview

API Documentation

Methods

attribute
Signature hs.spotlight.group:attribute() -> string
Type Method
Description

Returns the name of the attribute the spotlightGroupObject results are grouped by.
Parameters
  • None
Returns
  • the attribute name as a string
Source extensions/spotlight/libspotlight.m line 686
count
Signature hs.spotlight.group:count() -> integer
Type Method
Description

Returns the number of query results contained in the spotlightGroupObject.
Parameters
  • None
Returns
  • an integer specifying the number of results that match the attribute and value represented by this spotlightGroup object.
Notes
  • For convenience, metamethods have been added to the spotlightGroupObject which allow you to use #spotlightGroupObject as a shortcut for spotlightGroupObject:count().
Source extensions/spotlight/libspotlight.m line 722
resultAtIndex
Signature hs.spotlight.group:resultAtIndex(index) -> spotlightItemObject
Type Method
Description

Returns the spotlightItemObject at the specified index of the spotlightGroupObject
Parameters
  • index - an integer specifying the index of the result to return.
Returns
  • the spotlightItemObject at the specified index or an error if the index is out of bounds.
Notes
  • For convenience, metamethods have been added to the spotlightGroupObject which allow you to use spotlightGroupObject[index] as a shortcut for spotlightGroupObject:resultAtIndex(index).
Source extensions/spotlight/libspotlight.m line 743
subgroups
Signature hs.spotlight.group:subgroups() -> table
Type Method
Description

Returns the subgroups of the spotlightGroupObject
Parameters
  • None
Returns
  • an array table containing the subgroups of the spotlightGroupObject or nil if no subgroups exist
Notes
  • Subgroups are created when you supply more than one grouping attribute to hs.spotlight:groupingAttributes.
Source extensions/spotlight/libspotlight.m line 774
value
Signature hs.spotlight.group:value() -> value
Type Method
Description

Returns the value for the attribute the spotlightGroupObject results are grouped by.
Parameters
  • None
Returns
  • the attribute value as an appropriate data type
Source extensions/spotlight/libspotlight.m line 704