# 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

© Copyright 2025 LateNite Films Pty Ltd. All rights reserved.