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
• configurable
• favoriteChoices
• hiddenChoices
• lastQueryRemembered
• lastQueryValue
• 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
• favoriteChoice
• findChoice
• getActiveHandler
• getPopularity
• hide
• hideChoice
• id
• incPopularity
• isDisabledHandler
• isHiddenChoice
• isVisible
• onActivate
• preloadChoices
• refresh
• refreshChooser
• rightClickAction
• rightClickMain
• 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.

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.

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.

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.

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.

lastQueryRemembered

Signature	plugins.core.action.activator.lastQueryRemembered <cp.prop: boolean>
Type	Field
Description	If true, remember the last query.

lastQueryValue

Signature	plugins.core.action.activator.lastQueryValue <cp.prop: string>
Type	Field
Description	The last query value.

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

query

Signature	plugins.core.action.activator.query <cp.prop: string>
Type	Field
Description	The current "query" value for the activator.

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.

searchSubText

Signature	plugins.core.action.activator.searchSubText <cp.prop: boolean>
Type	Field
Description	If true, allow users to search the subtext value.

showHidden

Signature	plugins.core.action.activator.showHidden <cp.prop: boolean>
Type	Field
Description	If true, hidden items are shown.

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

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.
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(...) -> self
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	Self

chooser

Signature	plugins.core.action.activator:chooser() -> hs.chooser object
Type	Method
Description	Gets a hs.chooser
Parameters	None
Returns	A hs.chooser object

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

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([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

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 otherwise false.

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

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.

hide

Signature	plugins.core.action.activator:hide() -> none
Type	Method
Description	Hides a chooser listing the available actions.
Parameters	None
Returns	None

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.

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 unfavourited, otherwise false.

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.

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.

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() -> none
Type	Method
Description	Clears the existing set of choices and requests new ones from enabled action handlers.

refreshChooser

Signature	plugins.core.action.activator:refreshChooser() -> none
Type	Method
Description	Refreshes a Chooser.
Parameters	None
Returns	None

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

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

show

Signature	plugins.core.action.activator:show() -> boolean
Type	Method
Description	Shows a chooser listing the available actions. When selected by the user,
Parameters	None
Returns	true if successful

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, otherwise false.

toggle

Signature	plugins.core.action.activator:toggle() -> none
Type	Method
Description	Shows or hides the chooser.
Parameters	None
Returns	None

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

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.

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.

updateSelectedToolbarIcon

Signature	plugins.core.action.activator:updateSelectedToolbarIcon() -> none
Type	Method
Description	Updates the selected toolbar icon.
Parameters	None
Returns	None