command

​
Commands Module.
API Overview
Fields - Variables which can only be accessed from an object returned by a constructor
​isActive​
​isEnabled​
Methods - API calls which can only be made on an object returned by a constructor
​action​
​activated​
​activatedBy​
​addShortcut​
​deleteShortcuts​
​disable​
​enable​
​getAction​
​getFirstShortcut​
​getGroup​
​getImage​
​getShortcuts​
​getSubtitle​
​getTitle​
​groupedBy​
​hasAction​
​id​
​image​
​new​
​parent​
​pressed​
​released​
​repeated​
​setShortcuts​
​subtitled​
​titled​
​whenActivated​
​whenPressed​
​whenReleased​
​whenRepeated​
API Documentation
Fields
​isActive​
Signature
cp.commands.command.isActive <cp.prop: boolean; read-only>
Type
Field
Description
Indicates if the command is active. To be active, both the command and the group it belongs to must be enabled.
​isEnabled​
Signature
cp.commands.command.isEnabled <cp.prop: boolean>
Type
Field
Description
If set to true, the command is enabled.
Methods
​action​
Signature
cp.commands.command:action(getFn, setFn) -> command
Type
Method
Description
Sets the action get and set callbacks for a specific command.
Parameters
getFn - The function that gets the action.
setFn - The function that sets the action.
Returns
command - The command that was created.
Notes
The getFn function should have no arguments.
The setFn function can have two optional arguments:
clear - A boolean that defines whether or not the value should be cleared.
completionFn - An optional completion function callback.
​activated​
Signature
cp.commands.command:activated(repeats) -> command
Type
Method
Description
Executes the 'pressed', then 'repeated', then 'released' functions, if present.
Parameters
repeats - the number of times to repeat the 'repeated' function. Defaults to 1.
Returns
the last 'truthy' result (non-nil/false).
​activatedBy​
Signature
cp.commands.command:activatedBy([modifiers,] [keyCode]) -> command/modifier
Type
Method
Description
Specifies that the command is activated by pressing a key combination.
Parameters
modifiers - (optional) The table containing names of required modifiers.
keyCode - (optional) The key code that will activate the command, with no modifiers.
Returns
command if a keyCode was provided, or modifier if not.
​addShortcut​
Signature
cp.commands.command:addShortcut(newShortcut) -> command
Type
Method
Description
Adds the specified shortcut to the command.
Parameters
newShortcut - the shortcut to add.
Returns
self
​deleteShortcuts​
Signature
cp.commands.command:deleteShortcuts() -> command
Type
Method
Description
Sets the function that will be called when the command key combo is pressed.
Parameters
None
Returns
command - The current command
​disable​
Signature
cp.commands.command:disable() -> cp.commands.command
Type
Method
Description
Disables the command.
Parameters
None
Returns
The cp.commands.command instance.
​enable​
Signature
cp.commands.command:enable() -> cp.commands.command
Type
Method
Description
Enables the command.
Parameters
None
Returns
The cp.commands.command instance.
​getAction​
Signature
cp.commands.command:getAction() -> function, function
Type
Method
Description
Gets the action get and set callbacks for a specific command.
Parameters
None
Returns
getFn - The function that gets the action.
setFn - The function that sets the action.
​getFirstShortcut​
Signature
cp.commands.command:getFirstShortcut() -> command
Type
Method
Description
Returns the first shortcut, or nil if none have been registered.
Parameters
None
Returns
The first shortcut, or nil.
​getGroup​
Signature
cp.commands.command:getGroup() -> string
Type
Method
Description
Returns the group ID for the command.
Parameters
None
Returns
The group ID.
​getImage​
Signature
cp.commands.command:getImage() -> hs.image object
Type
Method
Description
Returns the current image.
Parameters
None
Returns
A hs.image object or nil if not is specified.
​getShortcuts​
Signature
cp.commands.command:getShortcuts() -> command
Type
Method
Description
Returns the set of shortcuts assigned to this command.
Parameters
None
Returns
The associated shortcuts.
​getSubtitle​
Signature
cp.commands.command:getSubtitle() -> string
Type
Method
Description
Returns the current subtitle, based on either the set subtitle, or the "_subtitle" value in the I18N files.
Parameters
None
Returns
The subtitle value or nil.
​getTitle​
Signature
cp.commands.command:getTitle() -> string
Type
Method
Description
Returns the command title in the current language, if availalbe. If not, the ID is returned.
Parameters
None
​groupedBy​
Signature
cp.commands.command:groupedBy(group) -> cp.commands.command
Type
Method
Description
Specifies that the command is grouped by a specific value.
Parameters
group - The group ID.
Returns
The cp.commands.command instance.
​hasAction​
Signature
cp.commands.command:hasAction() -> boolean
Type
Method
Description
Gets whether or not any action callbacks have been assigned.
Parameters
None
Returns
true if action callbacks have been assigned, otherwise false.
​id​
Signature
cp.commands.command:id() -> string
Type
Method
Description
Returns the ID for this command.
Parameters
None
Returns
The ID.
​image​
Signature
cp.commands.command:image(img) -> cp.commands.command
Type
Method
Description
Sets the specified image and returns the cp.commands.command instance.
Parameters
img - The hs.image to use.
Returns
The cp.commands.command instance.
​new​
Signature
cp.commands.command.new() -> command
Type
Method
Description
Creates a new command, which can have keyboard shortcuts assigned to it.
Parameters
id - the unique identifier for the command. E.g. 'cpCustomCommand'
parent - The parent group.
Returns
command - The command that was created.
​parent​
Signature
cp.commands.command:parent() -> cp.commands
Type
Method
Description
Returns the parent command group.
Parameters
None
​pressed​
Signature
cp.commands.command:pressed() -> command
Type
Method
Description
Executes the 'pressed' function, if present.
Parameters
None
Returns
the result of the function, or nil if none is present.
​released​
Signature
cp.commands.command:released() -> command
Type
Method
Description
Executes the 'released' function, if present.
Parameters
None
Returns
the result of the function, or nil if none is present.
​repeated​
Signature
cp.commands.command:repeated(repeats) -> command
Type
Method
Description
Executes the 'repeated' function, if present.
Parameters
repeats - the number of times to repeat. Defaults to 1.
Returns
the last result.
​setShortcuts​
Signature
cp.commands.command:setShortcuts(shortcuts) -> command
Type
Method
Description
Deletes any existing shortcuts and applies the new set of shortcuts in the table.
Parameters
shortcuts - The set of cp.commands.shortcuts to apply to this command.
Returns
The cp.commands.command instance.
​subtitled​
Signature
cp.commands.command:subtitled(subtitle) -> cp.commands.command
Type
Method
Description
Sets the specified subtitle and returns the cp.commands.command instance.
Parameters
subtitle - The new subtitle.
Returns
The cp.commands.command instance.
​titled​
Signature
cp.commands.command:titled(title) -> command
Type
Method
Description
Applies the provided human-readable title to the command.
Parameters
id - the unique identifier for the command (i.e. 'CPCustomCommand').
Returns
command - The command that was created.
​whenActivated​
Signature
cp.commands.command:whenActivated(activatedFn) -> command
Type
Method
Description
Sets the function that will be called when the command is activated.
Parameters
activatedFn - the function to call when activated.
Returns
command - The current command
​whenPressed​
Signature
cp.commands.command:whenPressed(pressedFn) -> command
Type
Method
Description
Sets the function that will be called when the command key combo is pressed.
Parameters
pressedFn - the function to call when pressed.
Returns
command - The current command
​whenReleased​
Signature
cp.commands.command:whenReleased(releasedFn) -> command
Type
Method
Description
Sets the function that will be called when the command key combo is released.
Parameters
releasedFn - the function to call when released.
Returns
command - The current command
​whenRepeated​
Signature
cp.commands.command:whenRepeated(repeatedFn) -> command
Type
Method
Description
Sets the function that will be called when the command key combo is repeated.
Parameters
repeatedFn - the function to call when repeated.
Returns
command - The current command

CommandPost API - Previous

commands

Next - CommandPost API

englishKeyCodes

Last modified 6mo ago

Export as PDF

Copy link

Contents

API Overview

API Documentation

Fields

​isActive​

​isEnabled​

Methods

​action​

​activated​

​activatedBy​

​addShortcut​

​deleteShortcuts​

​disable​

​enable​

​getAction​

​getFirstShortcut​

​getGroup​

​getImage​

​getShortcuts​

​getSubtitle​

​getTitle​

​groupedBy​

​hasAction​

​id​

​image​

​new​

​parent​

​pressed​

​released​

​repeated​

​setShortcuts​

​subtitled​

​titled​

​whenActivated​

​whenPressed​

​whenReleased​

​whenRepeated​

isActive

isEnabled

action

activated

activatedBy

addShortcut

deleteShortcuts

disable

enable

getAction

getFirstShortcut

getGroup

getImage

getShortcuts

getSubtitle

getTitle

groupedBy

hasAction

id

image

new

parent

pressed

released

repeated

setShortcuts

subtitled

titled

whenActivated

whenPressed

whenReleased

whenRepeated