# cp.commands

Commands Module.

# Submodules

# API Overview

Constants - Useful values which cannot be changed

DEFAULT_EXTENSION

Functions - API calls offered directly by the extension

getShortcutsPath
group
groupIds
groups
loadFromFile
new
saveToFile

Fields - Variables which can only be accessed from an object returned by a constructor

enabled
isEditable

Methods - API calls which can only be made on an object returned by a constructor

activate
add
clear
deleteShortcuts
disable
enable
get
getAll
id
loadShortcuts
saveShortcuts
watch

# API Documentation

# Constants

# DEFAULT_EXTENSION


Signature	`cp.commands.DEFAULT_EXTENSION -> string`
Type	Constant
Description	The menubar position priority.
Notes	None
Source	src/extensions/cp/commands/init.lua line 33

# Functions

# getShortcutsPath


Signature	`cp.commands.getShortcutsPath(name) -> string`
Type	Function
Description	Returns the path to the named shortcut set.
Parameters	None
Returns	A string
Notes	None
Examples	None
Source	src/extensions/cp/commands/init.lua line 379

# group


Signature	`cp.commands.group(id) -> cp.command or nil`
Type	Function
Description	Creates a collection of commands. These commands can be enabled or disabled as a group.
Parameters	`id` - The ID to retrieve
Returns	`cp.commands` - The command group with the specified ID, or `nil` if none exists.
Notes	None
Examples	None
Source	src/extensions/cp/commands/init.lua line 57

# groupIds


Signature	`cp.commands.groupIds() -> table`
Type	Function
Description	Returns an array of IDs of command groups which have been created.
Parameters	None
Returns	`table` - The array of group IDs.
Notes	None
Examples	None
Source	src/extensions/cp/commands/init.lua line 40

# groups


Signature	`cp.commands.groups(id) -> table of cp.commands`
Type	Function
Description	Returns a table with the set of commands.
Parameters	`id` - The ID to retrieve
Returns	`cp.commands` - The command group with the specified ID, or `nil` if none exists.
Notes	None
Examples	None
Source	src/extensions/cp/commands/init.lua line 70

# loadFromFile


Signature	`cp.commands.loadFromFile(name) -> boolean`
Type	Function
Description	Loads a shortcut set from the standard location with the specified name.
Parameters	name - The name of the shortcut set. E.g. "My Custom Shortcuts"
Returns	`true` if the file was found and loaded successfully.
Notes	None
Examples	None
Source	src/extensions/cp/commands/init.lua line 404

# new


Signature	`cp.commands.new(id) -> cp.commands`
Type	Function
Description	Creates a collection of commands. These commands can be enabled or disabled as a group.
Parameters	`id` - The unique ID for this command group.
Returns	cp.commands - The command group that was created.
Notes	None
Examples	None
Source	src/extensions/cp/commands/init.lua line 83

# saveToFile


Signature	`cp.commands.saveToFile(name) -> boolean`
Type	Function
Description	Saves the current shortcuts for all groups to a file in the standard location with the provided name.
Parameters	name - The name of the command set. E.g. "My Custom Commands"
Returns	`true` if the shortcuts were saved successfully.
Notes	None
Examples	None
Source	src/extensions/cp/commands/init.lua line 456

# Fields

# enabled


Signature	`cp.commands.enabled <cp.prop: boolean>`
Type	Field
Description	If enabled, the commands in the group will be active as well.
Notes	None
Source	src/extensions/cp/commands/init.lua line 104

# isEditable


Signature	`cp.commands.isEditable <cp.prop: boolean>`
Type	Field
Description	If set to `false`, the command group is not user-editable.
Notes	None
Source	src/extensions/cp/commands/init.lua line 116

# Methods

# activate


Signature	`cp.commands:activate(successFn, failureFn) -> nil`
Type	Method
Description	Will trigger an 'activate' event, and then execute either the `successFn` or `failureFn` if the command group is not enabled within 5 seconds.
Parameters	successFn - the function to call if successfully activated. failureFn - the function to call if not activated after 5 seconds.
Returns	Nothing.
Notes	None
Examples	None
Source	src/extensions/cp/commands/init.lua line 300

# add


Signature	`cp.commands:add(commandId) -> cp.commands.command`
Type	Method
Description	Adds a new command with the specified ID to this group. Additional configuration should be applied to the returned `command` instance. Eg:
Parameters	`commandId` - The unique ID for the new command.
Returns	The new `cp.commands.command` instance.
Notes	For example: lua</li><li>myCommands:add("fooBar"):groupedBy("foo"):whenActivated(function() ... end)`</li><li>
Examples	None
Source	src/extensions/cp/commands/init.lua line 139

# clear


Signature	`cp.commands:clear() -> cp.commands`
Type	Method
Description	Clears all commands and their shortcuts.
Parameters	None
Returns	The command group instance.
Notes	None
Examples	None
Source	src/extensions/cp/commands/init.lua line 197

# deleteShortcuts


Signature	`cp.commands:deleteShortcuts() -> cp.commands`
Type	Method
Description	Clears all shortcuts associated with commands in this command group.
Parameters	None
Returns	The command group instance.
Notes	None
Examples	None
Source	src/extensions/cp/commands/init.lua line 212

# disable


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

# enable


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

# get


Signature	`cp.commands:get(commandId) -> cp.commands.command`
Type	Method
Description	Returns the command with the specified ID, or `nil` if none exists.
Parameters	`commandId` - The command ID to retrieve.
Returns	The `cp.commands.command`, or `nil`.
Notes	None
Examples	None
Source	src/extensions/cp/commands/init.lua line 162

# getAll


Signature	`cp.commands:getAll() -> table of cp.commands.command`
Type	Method
Description	Returns the table of commands, with the key being the ID and the value being the command instance.
Parameters	None
Returns	A table
Notes	For example: `lua</li><li>for id,cmd in pairs(myCommands:getAll()) do</li><li> ...</li><li>end</li><li>`
Examples	None
Source	src/extensions/cp/commands/init.lua line 175

# id


Signature	`cp.commands:id() -> string`
Type	Method
Description	Returns the unique ID of the command group.
Parameters	None
Returns	The command group ID string.
Notes	None
Examples	None
Source	src/extensions/cp/commands/init.lua line 126

# loadShortcuts


Signature	`cp.commands:loadShortcuts(data) -> nil`
Type	Method
Description	Loads the shortcut details in the data table and applies them to the commands in this group. The data should probably come from the `saveShortcuts` method.
Parameters	data - The data table containing shortcuts.
Returns	Nothing
Notes	None
Examples	None
Source	src/extensions/cp/commands/init.lua line 358

# saveShortcuts


Signature	`cp.commands:saveShortcuts() -> table`
Type	Method
Description	Returns a table that is approprate to be saved to file that contains the shortuct for all contained `cp.commands.command` instances.
Parameters	None
Returns	The table of shortcuts for commands.
Notes	None
Examples	None
Source	src/extensions/cp/commands/init.lua line 333

# watch


Signature	`cp.commands:watch(events) -> cp.commands`
Type	Method
Description	Adds an event watcher to the command group.
Parameters	events - The table of events to watch for (see Notes).
Returns	The command group instance.
Notes	The table can have properties with the following functions, which will be called for the specific event: `add(command)`: Called after the provided `cp.commands.command` instance has been added. `activate()` Called when the command group is activated. `enable()`: Called when the command group is enabled. `disable()`: Called when the command group is disabled.
Examples	None
Source	src/extensions/cp/commands/init.lua line 256