plugins.core.action.activator

This module provides provides a way of activating choices provided by action handlers. It also provide support for making a particular action a favourite, returning results based on popularity, and completely hiding particular actions, or categories of action.

Activators are accessed via the action manager like so:

local activator = actionManager.getActivator("foobar")
activator:disableHandler("videoEffect")
activator:show()

Any changes made to the settings of a finder (such as calling disableHandler above) will be preserved for future loads of the finder with the same ID. They are also local to instances of this activator, so disabling "videoEffect" in the "foobar" activator will not affect the "yadayada" activator.

API Overview

Fields - Variables which can only be accessed from an object returned by a constructor

  • activeHandlers
  • allowedHandlers
  • configurable
  • favoriteChoices
  • hiddenChoices
  • lastQueryRemembered
  • lastQueryValue
  • lastRows
  • popularChoices
  • query
  • reducedTransparency
  • searchSubText
  • showHidden

Methods - API calls which can only be made on an object returned by a constructor

  • activate
  • activeChoices
  • allChoices
  • allowHandlers
  • chooser
  • disableAllHandlers
  • disableHandler
  • enableAllHandlers
  • enableHandler
  • enableHandlers
  • favoriteChoice
  • findChoice
  • getActiveHandler
  • getPopularity
  • hide
  • hideChoice
  • id
  • incPopularity
  • isDisabledHandler
  • isHiddenChoice
  • isVisible
  • onActivate
  • preloadChoices
  • refresh
  • refreshChooser
  • rightClickAction
  • rightClickMain
  • setBundleID
  • show
  • sortChoices
  • toggle
  • toolbarIcons
  • unfavoriteChoice
  • unhideChoice
  • updateSelectedToolbarIcon

API Documentation

Fields

activeHandlers

   
Signature plugins.core.action.activator.activeHandlers <cp.prop: table of handlers>
Type Field
Description Contains the table of active handlers. A handler is active if it is both allowed and enabled.
Notes None
Source src/plugins/core/action/manager/activator.lua line 214

allowedHandlers

   
Signature plugins.core.action.activator:allowedHandlers <cp.prop: table of handlers; read-only>
Type Field
Description Contains all handlers that are allowed in this activator.
Notes None
Source src/plugins/core/action/manager/activator.lua line 185

configurable

   
Signature plugins.core.action.activator.configurable <cp.prop: boolean>
Type Field
Description If true (the default), the activator can be configured by right-clicking on the main chooser.
Notes None
Source src/plugins/core/action/manager/activator.lua line 275

favoriteChoices

   
Signature plugins.core.action.activator.favoriteChoices <cp.prop: table of booleans>
Type Field
Description Contains the set of choice IDs which are favorites in this activator, mapped to a boolean value.
Notes None
Source src/plugins/core/action/manager/activator.lua line 257

hiddenChoices

   
Signature plugins.core.action.activator.hiddenChoices <cp.prop: table of booleans>
Type Field
Description Contains the set of choice IDs which are hidden in this activator, mapped to a boolean value.
Notes None
Source src/plugins/core/action/manager/activator.lua line 249

lastQueryRemembered

   
Signature plugins.core.action.activator.lastQueryRemembered <cp.prop: boolean>
Type Field
Description If true, remember the last query.
Notes None
Source src/plugins/core/action/manager/activator.lua line 141

lastQueryValue

   
Signature plugins.core.action.activator.lastQueryValue <cp.prop: string>
Type Field
Description The last query value.
Notes None
Source src/plugins/core/action/manager/activator.lua line 148

lastRows

   
Signature plugins.core.action.activator.lastRows <cp.prop: number>
Type Field
Description The last width of the Search Console. Defaults to 40.
Notes None
Source src/plugins/core/action/manager/activator.lua line 162

popularChoices

   
Signature plugins.core.action.activator.popularChoices <cp.prop: table of integers>
Type Field
Description Keeps track of how popular particular choices are. Returns a table of choice IDs
Notes None
Source src/plugins/core/action/manager/activator.lua line 266

query

   
Signature plugins.core.action.activator.query <cp.prop: string>
Type Field
Description The current "query" value for the activator.
Notes None
Source src/plugins/core/action/manager/activator.lua line 241

reducedTransparency

   
Signature plugins.core.action.activator.reducedTransparency <cp.prop: boolean>
Type Field
Description A property which will be true if the 'reduce transparency' mode is enabled.
Notes None
Source src/plugins/core/action/manager/activator.lua line 984

searchSubText

   
Signature plugins.core.action.activator.searchSubText <cp.prop: boolean>
Type Field
Description If true, allow users to search the subtext value.
Notes None
Source src/plugins/core/action/manager/activator.lua line 134

showHidden

   
Signature plugins.core.action.activator.showHidden <cp.prop: boolean>
Type Field
Description If true, hidden items are shown.
Notes None
Source src/plugins/core/action/manager/activator.lua line 169

Methods

activate

   
Signature plugins.core.action.activator:activate(result) -> none
Type Method
Description Triggered when the chooser is closed.
Parameters
  • result - The result from the chooser.
Returns
  • None
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 1518

activeChoices

   
Signature plugins.core.action.activator:activeChoices() -> table
Type Method
Description Returns a table with active choices. If a query is set, only choices containing the provided substring are returned. If showHidden is set to true hidden items are returned, otherwise they are not.
Parameters
  • None
Returns
  • Table of choices that can be displayed by an hs.chooser.
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 815

allChoices

   
Signature plugins.core.action.activator:allChoices() -> table
Type Method
Description Returns a table of all available choices, even if hidden. Choices from disabled action handlers are not included.
Parameters
  • None
Returns
  • Table of choices that can be displayed by an hs.chooser.
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 799

allowHandlers

   
Signature plugins.core.action.activator:allowHandlers(...) -> self
Type Method
Description Specifies that only the handlers with the specified IDs will be active in this activator. By default all handlers are allowed.
Parameters
  • ... - The list of Handler ID strings to allow.
Returns
  • Self
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 326

chooser

   
Signature plugins.core.action.activator:chooser() -> hs.chooser object
Type Method
Description Gets a hs.chooser
Parameters
  • None
Returns
  • A hs.chooser object
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 1069

disableAllHandlers

   
Signature plugins.core.action.activator:disableAllHandlers([groupID]) -> none
Type Method
Description Disables the all allowed handlers.
Parameters
  • groupID - An optional group ID to only disable all handlers of a specific group
Returns
  • None
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 455

disableHandler

   
Signature plugins.core.action.activator:disableHandler(id) -> boolean
Type Method
Description Disables the handler with the specified ID.
Parameters
  • id - The unique action handler ID.
Returns
  • true if the handler exists and was disabled.
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 363

enableAllHandlers

   
Signature plugins.core.action.activator:enableAllHandlers([groupID]) -> none
Type Method
Description Enables the all allowed handlers.
Parameters
  • groupID - An optional group ID to only enable all handlers of a specific group
Returns
  • None
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 428

enableHandler

   
Signature plugins.core.action.activator:enableHandler(id) -> boolean
Type Method
Description Enables the handler with the specified ID.
Parameters
  • id - The unique action handler ID.
Returns
  • true if the handler exists and was enabled.
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 383

enableHandlers

   
Signature plugins.core.action.activator:enableHandlers(groupID) -> none
Type Method
Description Enables the all allowed handlers of a specific group, and disables the everything else.
Parameters
  • groupID - The group ID to enable
Returns
  • None
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 403

favoriteChoice

   
Signature plugins.core.action.activator:favoriteChoice(id) -> boolean
Type Method
Description Marks the choice with the specified ID as a favorite.
Parameters
  • id - The choice ID to favorite.
Returns
  • true if successfully favorited otherwise false.
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 601

findChoice

   
Signature plugins.core.action.activator:findChoice(id) -> choice
Type Method
Description Gets a choice
Parameters
  • id - The choice ID.
Returns
  • The choice or nil if not found
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 500

getActiveHandler

   
Signature plugins.core.action.activator:getActiveHandler(id) -> handler
Type Method
Description Returns the active handler with the specified ID, or nil if not available.
Parameters
  • id - The Handler ID
Returns
  • The action handler, or nil.
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 313

getPopularity

   
Signature plugins.core.action.activator:getPopularity(id) -> boolean
Type Method
Description Returns the popularity of the specified choice.
Parameters
  • id - The choice ID to retrieve.
Returns
  • The number of times the choice has been executed.
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 652

hide

   
Signature plugins.core.action.activator:hide() -> none
Type Method
Description Hides a chooser listing the available actions.
Parameters
  • None
Returns
  • None
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 1432

hideChoice

   
Signature plugins.core.action.activator:hideChoice(id) -> boolean
Type Method
Description Hides the choice with the specified ID.
Parameters
  • id - The choice ID to hide.
Returns
  • true if successfully hidden otherwise false.
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 518

id

   
Signature plugins.core.action.activator:id() -> string
Type Method
Description Returns the activator's unique ID.
Parameters
  • None
Returns
  • The activator ID.
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 300

incPopularity

   
Signature plugins.core.action.activator:incPopularity(choice, id) -> boolean
Type Method
Description Increases the popularity of the specified choice.
Parameters
  • choice - The choice.
  • id - The choice ID to popularise.
Returns
  • true if successfully unfavourited, otherwise false.
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 669

isDisabledHandler

   
Signature plugins.core.action.activator:isDisabledHandler(id) -> boolean
Type Method
Description Returns true if the specified handler is disabled.
Parameters
  • id - The handler ID.
Returns
  • true if the handler is disabled.
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 486

isHiddenChoice

   
Signature plugins.core.action.activator:isHiddenChoice(id) -> boolean
Type Method
Description Checks if the specified choice is hidden.
Parameters
  • id - The choice ID to check.
Returns
  • true if currently hidden.
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 587

isVisible

   
Signature plugins.core.action.activator:isVisible() -> boolean
Type Method
Description Checks if the chooser is currently displayed.
Parameters
  • None
Returns
  • A boolean, true if the chooser is displayed on screen, false if not.
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 1329

onActivate

   
Signature plugins.core.action.activator:onActivate(activateFn) -> activator
Type Method
Description Registers the provided function to handle 'activate' actions, when the user selects an item in the main chooser.
Parameters
  • activateFn - The function to call when an item is activated.
Returns
  • The activator.
Notes
  • By default, the activator will 'execute' the action, but you can choose to provide an alternative action. It will get passed the handler object and the action table. Eg:
  • lua</li><li>activator:onActivate(function(handler, action))</li><li>
Examples None
Source src/plugins/core/action/manager/activator.lua line 1477

preloadChoices

   
Signature plugins.core.action.activator:preloadChoices([afterSeconds]) -> activator
Type Method
Description Indicates the activator should preload the choices after a number of seconds. Defaults to 0 seconds if no value is provided.
Parameters
  • afterSeconds - The number of seconds to wait before preloading.
Returns
  • The activator.
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 282

refresh

   
Signature plugins.core.action.activator:refresh() -> none
Type Method
Description Clears the existing set of choices and requests new ones from enabled action handlers.
Parameters
  • None
Returns
  • None
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 971

refreshChooser

   
Signature plugins.core.action.activator:refreshChooser() -> none
Type Method
Description Refreshes a Chooser.
Parameters
  • None
Returns
  • None
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 1310

rightClickAction

   
Signature plugins.core.action.activator:rightClickAction(index) -> none
Type Method
Description Triggered when a user right clicks on a chooser.
Parameters
  • index - The row the right click occurred in or 0 if there is currently no selectable row where the right click occurred.
Returns
  • None
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 1560

rightClickMain

   
Signature plugins.core.action.activator:rightClickMain(index) -> none
Type Method
Description Triggered when a user right clicks on a chooser.
Parameters
  • index - The row the right click occurred in or 0 if there is currently no selectable row where the right click occurred.
Returns
  • None
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 1547

setBundleID

   
Signature plugins.core.action.activator:setBundleID(bundleID, icon, displayName) -> self
Type Method
Description Sets a bundle ID to use for filtering purposes.
Parameters
  • bundleID - An application bundle ID as string.
  • icon - An application icon as an hs.image object.
  • displayName - The application display name as a string.
Returns
  • Self
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 109

show

   
Signature plugins.core.action.activator:show() -> boolean
Type Method
Description Shows a chooser listing the available actions. When selected by the user, the onActivate function is called.
Parameters
  • None
Returns
  • true if successful
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 1348

sortChoices

   
Signature plugins.core.action.activator:sortChoices() -> boolean
Type Method
Description Sorts the current set of choices in the activator. It takes into account whether it's a favorite (first priority) and its overall popularity.
Parameters
  • None
Returns
  • true if the action executed successfully, otherwise false.
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 783

toggle

   
Signature plugins.core.action.activator:toggle() -> none
Type Method
Description Shows or hides the chooser.
Parameters
  • None
Returns
  • None
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 1460

toolbarIcons

   
Signature plugins.core.action.activator:toolbarIcons(table) -> self
Type Method
Description Sets which sections have an icon on the toolbar.
Parameters
  • table - A table containing paths to all the toolbar icons. The key should be the handler ID, and the value should be the path to the icon.
Returns
  • Self
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 348

unfavoriteChoice

   
Signature plugins.core.action.activator:unfavoriteChoice(id) -> boolean
Type Method
Description Marks the choice with the specified ID as not a favorite.
Parameters
  • id - The choice ID to unfavorite.
Returns
  • true if successfully unfavorited.
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 627

unhideChoice

   
Signature plugins.core.action.activator:unhideChoice(id) -> boolean
Type Method
Description Reveals the choice with the specified ID.
Parameters
  • id - The choice ID to hide.
Returns
  • true if successfully unhidden otherwise false.
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 547

updateSelectedToolbarIcon

   
Signature plugins.core.action.activator:updateSelectedToolbarIcon() -> none
Type Method
Description Updates the selected toolbar icon.
Parameters
  • None
Returns
  • None
Notes None
Examples None
Source src/plugins/core/action/manager/activator.lua line 991

© Copyright 2026 LateNite Films Pty Ltd. All rights reserved.