#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