plugins.core.action.activator.md

docs » 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
• hiddenChoices
• Methods - API calls which can only be made on an object returned by a constructor
• activeChoices
• allChoices
• allowHandlers
• disableAllHandlers
• disableHandler
• enableAllHandlers
• enableHandler
• favoriteChoice
• getActiveHandler
• getPopularity
• hideChoice
• id
• incPopularity
• isDisabledHandler
• isHiddenChoice
• onActivate
• preloadChoices
• refresh
• show
• sortChoices
• unfavoriteChoice
• unhiddenChoices
• unhideChoice

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.

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.

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.

Methods

activeChoices

Signature	plugins.core.action.activator:activeChoices() -> table
Type	Method
Description	Returns a table with active choices. If showHidden is set to true hidden
Parameters	* None
Returns	* Table of choices that can be displayed by an hs.chooser.

allChoices

Signature	plugins.core.action.activator:allChoices() -> table
Type	Method
Description	Returns a table of all available choices, even if hidden. Choices from
Parameters	* None
Returns	* Table of choices that can be displayed by an hs.chooser.

allowHandlers

Signature	plugins.core.action.activator:allowHandlers(...) -> boolean
Type	Method
Description	Specifies that only the handlers with the specified IDs will be active in
Parameters	* ... - The list of Handler ID strings to allow.
Returns	* true if the handlers were found.

disableAllHandlers

Signature	plugins.core.action.activator:disableAllHandlers() -> nothing
Type	Method
Description	Disables the all allowed handlers.
Parameters	* None
Returns	* Nothing

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.

enableAllHandlers

Signature	plugins.core.action.activator:enableAllHandlers() -> nothing
Type	Method
Description	Enables the all allowed handlers.
Parameters	* None
Returns	* Nothing

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.

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.

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.

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.

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.

id

Signature	plugins.core.action.activator:id() -> string
Type	Method
Description	Returns the activator's unique ID.
Parameters	* None
Returns	* The activator ID.

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 unfavorited.

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.

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.

onActivate

Signature	plugins.core.action.activator:onActivate(activateFn) -> activator
Type	Method
Description	Registers the provided function to handle 'activate' actions, when the user selects
Parameters	* activateFn - The function to call when an item is activated.
Returns	* The activator.

preloadChoices

Signature	plugins.core.action.activator:preloadChoices([afterSeconds]) -> activator
Type	Method
Description	Indicates the activator should preload the choices after a number of seconds.
Parameters	* afterSeconds - The number of seconds to wait before preloading.
Returns	* The activator.

refresh

Signature	plugins.core.action.activator:refresh()
Type	Method
Description	Clears the existing set of choices and requests new ones from enabled action handlers.

show

Signature	plugins.core.action.activator:show()
Type	Method
Description	Shows a chooser listing the available actions. When selected by the user,
Parameters	* None
Returns	* Nothing

sortChoices

Signature	plugins.core.action.activator:sortChoices() -> boolean
Type	Method
Description	Sorts the current set of choices in the activator. It takes into account
Parameters	* None
Returns	* true if the action executed successfully.

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.

unhiddenChoices

Signature	plugins.core.action.activator:unhiddenChoices() -> table
Type	Method
Description	Returns a table with visible choices.
Parameters	* None
Returns	* Table of choices that can be displayed by an hs.chooser.

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.