Getting Started
Contributing
Control CommandPost
Plugins
Internationalisation
CommandPost API
Bundled Plugins API
Hammerspoon API
command
​
Commands Module.
API Overview
- Fields - Variables which can only be accessed from an object returned by a constructor
- Methods - API calls which can only be made on an object returned by a constructor
API Documentation
Fields
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.
Signature
cp.commands.command.isEnabled <cp.prop: boolean>Type
Field
Description
If set to
true, the command is enabled.Methods
Signature
cp.commands.command:action(getFn, setFn) -> commandType
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
getFnfunction should have no arguments. - The
setFnfunction can have two optional arguments: clear- A boolean that defines whether or not the value should be cleared.completionFn- An optional completion function callback.
Signature
cp.commands.command:activated(repeats) -> commandType
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).
Signature
cp.commands.command:activatedBy([modifiers,] [keyCode]) -> command/modifierType
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
commandif akeyCodewas provided, ormodifierif not.
Signature
cp.commands.command:addShortcut(newShortcut) -> commandType
Method
Description
Adds the specified shortcut to the command.
Parameters
newShortcut- the shortcut to add.
Returns
self
Signature
cp.commands.command:deleteShortcuts() -> commandType
Method
Description
Sets the function that will be called when the command key combo is pressed.
Parameters
- None
Returns
- command - The current command
Signature
cp.commands.command:disable() -> cp.commands.commandType
Method
Description
Disables the command.
Parameters
- None
Returns
- The
cp.commands.commandinstance.
Signature
cp.commands.command:enable() -> cp.commands.commandType
Method
Description
Enables the command.
Parameters
- None
Returns
- The
cp.commands.commandinstance.
Signature
cp.commands.command:getAction() -> function, functionType
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.
Signature
cp.commands.command:getFirstShortcut() -> commandType
Method
Description
Returns the first shortcut, or
nil if none have been registered.Parameters
- None
Returns
- The first shortcut, or
nil.
Signature
cp.commands.command:getGroup() -> stringType
Method
Description
Returns the group ID for the command.
Parameters
- None
Returns
- The group ID.
Signature
cp.commands.command:getImage() -> hs.image objectType
Method
Description
Returns the current image.
Parameters
- None
Returns
- A hs.image object or
nilif not is specified.
Signature
cp.commands.command:getShortcuts() -> commandType
Method
Description
Returns the set of shortcuts assigned to this command.
Parameters
- None
Returns
- The associated shortcuts.
Signature
cp.commands.command:getSubtitle() -> stringType
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.
Signature
cp.commands.command:getTitle() -> stringType
Method
Description
Returns the command title in the current language, if availalbe. If not, the ID is returned.
Parameters
- None
Signature
cp.commands.command:groupedBy(group) -> cp.commands.commandType
Method
Description
Specifies that the command is grouped by a specific value.
Parameters
group- The group ID.
Returns
- The
cp.commands.commandinstance.
Signature
cp.commands.command:hasAction() -> booleanType
Method
Description
Gets whether or not any action callbacks have been assigned.
Parameters
- None
Returns
trueif action callbacks have been assigned, otherwisefalse.
Signature
cp.commands.command:id() -> stringType
Method
Description
Returns the ID for this command.
Parameters
- None
Returns
- The ID.
Signature
cp.commands.command:image(img) -> cp.commands.commandType
Method
Description
Sets the specified image and returns the
cp.commands.command instance.Parameters
img- Thehs.imageto use.
Returns
- The
cp.commands.commandinstance.
Signature
cp.commands.command.new() -> commandType
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.
Signature
cp.commands.command:parent() -> cp.commandsType
Method
Description
Returns the parent command group.
Parameters
- None
Signature
cp.commands.command:pressed() -> commandType
Method
Description
Executes the 'pressed' function, if present.
Parameters
- None
Returns
- the result of the function, or
nilif none is present.
Signature
cp.commands.command:released() -> commandType
Method
Description
Executes the 'released' function, if present.
Parameters
- None
Returns
- the result of the function, or
nilif none is present.
Signature
cp.commands.command:repeated(repeats) -> commandType
Method
Description
Executes the 'repeated' function, if present.
Parameters
repeats- the number of times to repeat. Defaults to 1.
Returns
- the last result.
Signature
cp.commands.command:setShortcuts(shortcuts) -> commandType
Method
Description
Deletes any existing shortcuts and applies the new set of shortcuts in the table.
Parameters
- shortcuts - The set of
cp.commands.shortcutsto apply to this command.
Returns
- The
cp.commands.commandinstance.
Signature
cp.commands.command:subtitled(subtitle) -> cp.commands.commandType
Method
Description
Sets the specified subtitle and returns the
cp.commands.command instance.Parameters
subtitle- The new subtitle.
Returns
- The
cp.commands.commandinstance.
Signature
cp.commands.command:titled(title) -> commandType
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.
Signature
cp.commands.command:whenActivated(activatedFn) -> commandType
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
Signature
cp.commands.command:whenPressed(pressedFn) -> commandType
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
Signature
cp.commands.command:whenReleased(releasedFn) -> commandType
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
Signature
cp.commands.command:whenRepeated(repeatedFn) -> commandType
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
Last modified 1mo ago
Export as PDF
Copy link