#cp.commands.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.
Notes	None
Source	src/extensions/cp/commands/command.lua line 38

#isEnabled


Signature	`cp.commands.command.isEnabled <cp.prop: boolean>`
Type	Field
Description	If set to `true`, the command is enabled.
Notes	None
Source	src/extensions/cp/commands/command.lua line 33

#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.
Examples	None
Source	src/extensions/cp/commands/command.lua line 95

#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).
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 493

#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.
Notes	This method can be called multiple times, and multiple key combinations will be registered for the command. To remove existing key combinations, call the `command:deleteShortcuts()` method. If the `keyCode` is provided, no modifiers need to be pressed to activate and the `command` is returned. If the `modifiers` and `keyCode` are provided, the combination is created and the `command` is returned. ** If no `keyCode` is provided, a `modifier` is returned, which lets you specify keyboard combinations. For example: `</li><li>local global = commands.collection("global")</li><li>local pressA = global:add("commandA"):activatedBy("a")</li><li>local pressShiftA = global:add("commandShiftA"):activatedBy({"shift"}, "a")</li><li>local pressCmdA = global:add("commandCmdA"):activatedBy():command("a")</li><li>local pressOptCmdA = global:add("commandOptCmdA"):activatedBy():option():command("a")</li><li>global:enable()</li><li>`
Examples	None
Source	src/extensions/cp/commands/command.lua line 253

#addShortcut


Signature	`cp.commands.command:addShortcut(newShortcut) -> command`
Type	Method
Description	Adds the specified shortcut to the command. If the command is enabled, the shortcut will also be enabled.
Parameters	`newShortcut` - the shortcut to add.
Returns	`self`
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 334

#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
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 300

#disable


Signature	`cp.commands.command:disable() -> cp.commands.command`
Type	Method
Description	Disables the command.
Parameters	None
Returns	The `cp.commands.command` instance.
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 526

#enable


Signature	`cp.commands.command:enable() -> cp.commands.command`
Type	Method
Description	Enables the command.
Parameters	None
Returns	The `cp.commands.command` instance.
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 512

#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.
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 117

#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`.
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 372

#getGroup


Signature	`cp.commands.command:getGroup() -> string`
Type	Method
Description	Returns the group ID for the command.
Parameters	None
Returns	The group ID.
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 240

#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.
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 210

#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.
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 359

#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. If nothing is available, it will return `nil`.
Parameters	None
Returns	The subtitle value or `nil`.
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 179

#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
Returns	The human-readable command title.
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 144

#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.
Notes	This is different to the command group/parent value.
Examples	None
Source	src/extensions/cp/commands/command.lua line 223

#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`.
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 131

#id


Signature	`cp.commands.command:id() -> string`
Type	Method
Description	Returns the ID for this command.
Parameters	None
Returns	The ID.
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 55

#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.
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 196

#new


Signature	`cp.commands.command.new(id, parent) -> 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.
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 16

#parent


Signature	`cp.commands.command:parent() -> cp.commands`
Type	Method
Description	Returns the parent command group.
Parameters	None
Returns	The parent `cp.commands`.
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 68

#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.
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 443

#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.
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 457

#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.
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 471

#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.
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 317

#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.
Notes	By default, it will look up the `<ID>_subtitle` value. Anything set here will override it in all langauges.
Examples	None
Source	src/extensions/cp/commands/command.lua line 161

#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.
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 81

#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
Notes	This is a shortcut for calling `whenPressed(...)`
Examples	None
Source	src/extensions/cp/commands/command.lua line 385

#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
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 401

#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
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 415

#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
Notes	None
Examples	None
Source	src/extensions/cp/commands/command.lua line 429