0
# Command Management
1
2
Core functionality for registering, managing and executing commands. Commands are the fundamental unit of functionality in the registry, representing abstract actions that can be executed with contextual arguments.
3
4
## Capabilities
5
6
### CommandRegistry Class
7
8
The central registry that manages all commands in the application.
9
10
```typescript { .api }
11
/**
12
* An object which manages a collection of commands.
13
* A command registry can be used to populate a variety of action-based
14
* widgets, such as command palettes, menus, and toolbars.
15
*/
16
class CommandRegistry {
17
constructor();
18
}
19
```
20
21
### Command Registration
22
23
Add and remove commands from the registry with comprehensive configuration options.
24
25
```typescript { .api }
26
/**
27
* Add a command to the registry.
28
* @param id - The unique id of the command
29
* @param options - The options for the command
30
* @returns A disposable which will remove the command
31
* @throws An error if the given id is already registered
32
*/
33
addCommand(id: string, options: CommandRegistry.ICommandOptions): IDisposable;
34
35
/**
36
* Test whether a specific command is registered.
37
* @param id - The id of the command of interest
38
* @returns true if the command is registered, false otherwise
39
*/
40
hasCommand(id: string): boolean;
41
42
/**
43
* List the ids of the registered commands.
44
* @returns A new array of the registered command ids
45
*/
46
listCommands(): string[];
47
```
48
49
### Command Options Interface
50
51
Configuration object for creating commands with all available options.
52
53
```typescript { .api }
54
interface ICommandOptions {
55
/** The function to invoke when the command is executed (required) */
56
execute: CommandFunc<any | Promise<any>>;
57
58
/** JSON Schemas describing the command */
59
describedBy?: Partial<Description> | CommandFunc<Partial<Description> | Promise<Partial<Description>>>;
60
61
/** The label for the command */
62
label?: string | CommandFunc<string>;
63
64
/** The index of the mnemonic character in the command's label */
65
mnemonic?: number | CommandFunc<number>;
66
67
/** The icon renderer for the command */
68
icon?: VirtualElement.IRenderer | undefined | CommandFunc<VirtualElement.IRenderer | undefined>;
69
70
/** The icon class for the command */
71
iconClass?: string | CommandFunc<string>;
72
73
/** The icon label for the command */
74
iconLabel?: string | CommandFunc<string>;
75
76
/** The caption for the command */
77
caption?: string | CommandFunc<string>;
78
79
/** The usage text for the command */
80
usage?: string | CommandFunc<string>;
81
82
/** The general class name for the command */
83
className?: string | CommandFunc<string>;
84
85
/** The dataset for the command */
86
dataset?: Dataset | CommandFunc<Dataset>;
87
88
/** A function which indicates whether the command is enabled */
89
isEnabled?: CommandFunc<boolean>;
90
91
/** A function which indicates whether the command is toggled */
92
isToggled?: CommandFunc<boolean>;
93
94
/** A function which indicates whether the command is toggleable */
95
isToggleable?: boolean;
96
97
/** A function which indicates whether the command is visible */
98
isVisible?: CommandFunc<boolean>;
99
}
100
```
101
102
### Command Execution
103
104
Execute registered commands with optional arguments.
105
106
```typescript { .api }
107
/**
108
* Execute a specific command.
109
* @param id - The id of the command of interest
110
* @param args - The arguments for the command
111
* @returns A promise which resolves with the result of the command
112
* @throws The promise will reject if the command throws an exception or if the command is not registered
113
*/
114
execute(id: string, args?: ReadonlyPartialJSONObject): Promise<any>;
115
```
116
117
### Command State Notification
118
119
Notify the registry when command state has changed to trigger UI updates.
120
121
```typescript { .api }
122
/**
123
* Notify listeners that the state of a command has changed.
124
* @param id - The id of the command which has changed. If more than one command has changed, this argument should be omitted
125
* @throws An error if the given id is not registered
126
*/
127
notifyCommandChanged(id?: string): void;
128
```
129
130
## Usage Examples
131
132
### Basic Command Registration
133
134
```typescript
135
import { CommandRegistry } from "@lumino/commands";
136
137
const registry = new CommandRegistry();
138
139
// Simple command with static properties
140
const disposable = registry.addCommand("simple-command", {
141
execute: () => {
142
console.log("Command executed!");
143
},
144
label: "Simple Command",
145
caption: "A simple example command"
146
});
147
148
// Execute the command
149
await registry.execute("simple-command");
150
```
151
152
### Dynamic Command Properties
153
154
```typescript
155
import { CommandRegistry } from "@lumino/commands";
156
157
const registry = new CommandRegistry();
158
159
// Command with dynamic properties based on arguments
160
registry.addCommand("dynamic-command", {
161
execute: (args) => {
162
console.log(`Processing ${args.filename}`);
163
return Promise.resolve(`Processed ${args.filename}`);
164
},
165
label: (args) => args.filename ? `Process ${args.filename}` : "Process File",
166
isEnabled: (args) => Boolean(args.filename),
167
isVisible: (args) => Boolean(args.canProcess)
168
});
169
170
// Execute with different arguments
171
await registry.execute("dynamic-command", {
172
filename: "document.txt",
173
canProcess: true
174
});
175
```
176
177
### Command State Management
178
179
```typescript
180
import { CommandRegistry } from "@lumino/commands";
181
182
const registry = new CommandRegistry();
183
let documentModified = false;
184
185
registry.addCommand("save-document", {
186
execute: () => {
187
console.log("Saving document...");
188
documentModified = false;
189
// Notify that command state has changed
190
registry.notifyCommandChanged("save-document");
191
return Promise.resolve();
192
},
193
label: "Save Document",
194
isEnabled: () => documentModified,
195
iconClass: () => documentModified ? "fa fa-save" : "fa fa-save disabled"
196
});
197
198
// Simulate document modification
199
documentModified = true;
200
registry.notifyCommandChanged("save-document");
201
202
// Now the save command will be enabled
203
await registry.execute("save-document");
204
```
205
206
### Command Registry Management
207
208
```typescript
209
import { CommandRegistry } from "@lumino/commands";
210
211
const registry = new CommandRegistry();
212
213
// Add multiple commands
214
const disposables = [
215
registry.addCommand("cut", { execute: () => console.log("Cut") }),
216
registry.addCommand("copy", { execute: () => console.log("Copy") }),
217
registry.addCommand("paste", { execute: () => console.log("Paste") })
218
];
219
220
// List all registered commands
221
console.log(registry.listCommands()); // ["cut", "copy", "paste"]
222
223
// Check if commands exist
224
console.log(registry.hasCommand("cut")); // true
225
console.log(registry.hasCommand("undo")); // false
226
227
// Clean up all commands
228
disposables.forEach(d => d.dispose());
229
console.log(registry.listCommands()); // []
230
```
231
232
## Types
233
234
```typescript { .api }
235
type CommandFunc<T> = (args: ReadonlyPartialJSONObject) => T;
236
type Dataset = { readonly [key: string]: string };
237
type Description = { args: ReadonlyJSONObject | null };
238
```