1 | import { Event, Emitter, WaitUntilEvent } from './event';
|
2 | import { Disposable } from './disposable';
|
3 | import { ContributionProvider } from './contribution-provider';
|
4 | /**
|
5 | * A command is a unique identifier of a function
|
6 | * which can be executed by a user via a keyboard shortcut,
|
7 | * a menu action or directly.
|
8 | */
|
9 | export interface Command {
|
10 | /**
|
11 | * A unique identifier of this command.
|
12 | */
|
13 | id: string;
|
14 | /**
|
15 | * A label of this command.
|
16 | */
|
17 | label?: string;
|
18 | originalLabel?: string;
|
19 | /**
|
20 | * An icon class of this command.
|
21 | */
|
22 | iconClass?: string;
|
23 | /**
|
24 | * A category of this command.
|
25 | */
|
26 | category?: string;
|
27 | originalCategory?: string;
|
28 | }
|
29 | export declare namespace Command {
|
30 | function is(arg: unknown): arg is Command;
|
31 | /** Utility function to easily translate commands */
|
32 | function toLocalizedCommand(command: Command, nlsLabelKey?: string, nlsCategoryKey?: string): Command;
|
33 | function toDefaultLocalizedCommand(command: Command): Command;
|
34 | /** Comparator function for when sorting commands */
|
35 | function compareCommands(a: Command, b: Command): number;
|
36 | /**
|
37 | * Determine if two commands are equal.
|
38 | *
|
39 | * @param a the first command for comparison.
|
40 | * @param b the second command for comparison.
|
41 | */
|
42 | function equals(a: Command, b: Command): boolean;
|
43 | }
|
44 | /**
|
45 | * A command handler is an implementation of a command.
|
46 | *
|
47 | * A command can have multiple handlers
|
48 | * but they should be active in different contexts,
|
49 | * otherwise first active will be executed.
|
50 | */
|
51 | export interface CommandHandler {
|
52 | /**
|
53 | * Execute this handler.
|
54 | *
|
55 | * Don't call it directly, use `CommandService.executeCommand` instead.
|
56 | */
|
57 | execute(...args: any[]): any;
|
58 | /**
|
59 | * Test whether this handler is enabled (active).
|
60 | */
|
61 | isEnabled?(...args: any[]): boolean;
|
62 | /**
|
63 | * Test whether menu items for this handler should be visible.
|
64 | */
|
65 | isVisible?(...args: any[]): boolean;
|
66 | /**
|
67 | * Test whether menu items for this handler should be toggled.
|
68 | */
|
69 | isToggled?(...args: any[]): boolean;
|
70 | }
|
71 | export declare const CommandContribution: unique symbol;
|
72 | /**
|
73 | * The command contribution should be implemented to register custom commands and handler.
|
74 | */
|
75 | export interface CommandContribution {
|
76 | /**
|
77 | * Register commands and handlers.
|
78 | */
|
79 | registerCommands(commands: CommandRegistry): void;
|
80 | }
|
81 | export interface CommandEvent {
|
82 | commandId: string;
|
83 | args: any[];
|
84 | }
|
85 | export interface WillExecuteCommandEvent extends WaitUntilEvent, CommandEvent {
|
86 | }
|
87 | export declare const commandServicePath = "/services/commands";
|
88 | export declare const CommandService: unique symbol;
|
89 | /**
|
90 | * The command service should be used to execute commands.
|
91 | */
|
92 | export interface CommandService {
|
93 | /**
|
94 | * Execute the active handler for the given command and arguments.
|
95 | *
|
96 | * Reject if a command cannot be executed.
|
97 | */
|
98 | executeCommand<T>(command: string, ...args: any[]): Promise<T | undefined>;
|
99 | /**
|
100 | * An event is emitted when a command is about to be executed.
|
101 | *
|
102 | * It can be used to install or activate a command handler.
|
103 | */
|
104 | readonly onWillExecuteCommand: Event<WillExecuteCommandEvent>;
|
105 | /**
|
106 | * An event is emitted when a command was executed.
|
107 | */
|
108 | readonly onDidExecuteCommand: Event<CommandEvent>;
|
109 | }
|
110 | /**
|
111 | * The command registry manages commands and handlers.
|
112 | */
|
113 | export declare class CommandRegistry implements CommandService {
|
114 | protected readonly contributionProvider: ContributionProvider<CommandContribution>;
|
115 | protected readonly _commands: {
|
116 | [id: string]: Command;
|
117 | };
|
118 | protected readonly _handlers: {
|
119 | [id: string]: CommandHandler[];
|
120 | };
|
121 | protected readonly toUnregisterCommands: Map<string, Disposable>;
|
122 | protected _recent: string[];
|
123 | protected readonly onWillExecuteCommandEmitter: Emitter<WillExecuteCommandEvent>;
|
124 | readonly onWillExecuteCommand: Event<WillExecuteCommandEvent>;
|
125 | protected readonly onDidExecuteCommandEmitter: Emitter<CommandEvent>;
|
126 | readonly onDidExecuteCommand: Event<CommandEvent>;
|
127 | protected readonly onCommandsChangedEmitter: Emitter<void>;
|
128 | readonly onCommandsChanged: Event<void>;
|
129 | constructor(contributionProvider: ContributionProvider<CommandContribution>);
|
130 | onStart(): void;
|
131 | getAllCommands(): IterableIterator<Readonly<Command & {
|
132 | handlers: CommandHandler[];
|
133 | }>>;
|
134 | /**
|
135 | * Register the given command and handler if present.
|
136 | *
|
137 | * Throw if a command is already registered for the given command identifier.
|
138 | */
|
139 | registerCommand(command: Command, handler?: CommandHandler): Disposable;
|
140 | protected doRegisterCommand(command: Command): Disposable;
|
141 | /**
|
142 | * Unregister command from the registry
|
143 | *
|
144 | * @param command
|
145 | */
|
146 | unregisterCommand(command: Command): void;
|
147 | /**
|
148 | * Unregister command from the registry
|
149 | *
|
150 | * @param id
|
151 | */
|
152 | unregisterCommand(id: string): void;
|
153 | /**
|
154 | * Register the given handler for the given command identifier.
|
155 | *
|
156 | * If there is already a handler for the given command
|
157 | * then the given handler is registered as more specific, and
|
158 | * has higher priority during enablement, visibility and toggle state evaluations.
|
159 | */
|
160 | registerHandler(commandId: string, handler: CommandHandler): Disposable;
|
161 | protected fireDidChange: () => Promise<void>;
|
162 | protected doFireDidChange(): void;
|
163 | /**
|
164 | * Test whether there is an active handler for the given command.
|
165 | */
|
166 | isEnabled(command: string, ...args: any[]): boolean;
|
167 | /**
|
168 | * Test whether there is a visible handler for the given command.
|
169 | */
|
170 | isVisible(command: string, ...args: any[]): boolean;
|
171 | /**
|
172 | * Test whether there is a toggled handler for the given command.
|
173 | */
|
174 | isToggled(command: string, ...args: any[]): boolean;
|
175 | /**
|
176 | * Execute the active handler for the given command and arguments.
|
177 | *
|
178 | * Reject if a command cannot be executed.
|
179 | */
|
180 | executeCommand<T>(commandId: string, ...args: any[]): Promise<T | undefined>;
|
181 | protected fireWillExecuteCommand(commandId: string, args?: any[]): Promise<void>;
|
182 | /**
|
183 | * Get a visible handler for the given command or `undefined`.
|
184 | */
|
185 | getVisibleHandler(commandId: string, ...args: any[]): CommandHandler | undefined;
|
186 | /**
|
187 | * Get an active handler for the given command or `undefined`.
|
188 | */
|
189 | getActiveHandler(commandId: string, ...args: any[]): CommandHandler | undefined;
|
190 | /**
|
191 | * Get a toggled handler for the given command or `undefined`.
|
192 | */
|
193 | getToggledHandler(commandId: string, ...args: any[]): CommandHandler | undefined;
|
194 | /**
|
195 | * Returns with all handlers for the given command. If the command does not have any handlers,
|
196 | * or the command is not registered, returns an empty array.
|
197 | */
|
198 | getAllHandlers(commandId: string): CommandHandler[];
|
199 | /**
|
200 | * Get all registered commands.
|
201 | */
|
202 | get commands(): Command[];
|
203 | /**
|
204 | * Get a command for the given command identifier.
|
205 | */
|
206 | getCommand(id: string): Command | undefined;
|
207 | /**
|
208 | * Get all registered commands identifiers.
|
209 | */
|
210 | get commandIds(): string[];
|
211 | /**
|
212 | * Get the list of recently used commands.
|
213 | */
|
214 | get recent(): Command[];
|
215 | /**
|
216 | * Set the list of recently used commands.
|
217 | * @param commands the list of recently used commands.
|
218 | */
|
219 | set recent(commands: Command[]);
|
220 | /**
|
221 | * Adds a command to recently used list.
|
222 | * Prioritizes commands that were recently executed to be most recent.
|
223 | *
|
224 | * @param recent a recent command, or array of recent commands.
|
225 | */
|
226 | addRecentCommand(recent: Command | Command[]): void;
|
227 | /**
|
228 | * Clear the list of recently used commands.
|
229 | */
|
230 | clearCommandHistory(): void;
|
231 | }
|
232 | //# sourceMappingURL=command.d.ts.map |
\ | No newline at end of file |