cp.commands.command.md

docs » 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.

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