Internationalisation
Bundled Plugins API
command
Commands Module.

API Overview

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).
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.
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
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.
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.
Signature
cp.commands.command:getShortcuts() -> command
Type
Method
Description
Returns the set of shortcuts assigned to this command.
Parameters
  • None
Returns
  • The associated shortcuts.
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.
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.
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
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
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
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
Last modified 1mo ago
Export as PDF
Copy link