-
Notifications
You must be signed in to change notification settings - Fork 268
/
extension-api.d.ts
2663 lines (2370 loc) · 81.9 KB
/
extension-api.d.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/**********************************************************************
* Copyright (C) 2022-2023 Red Hat, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
* SPDX-License-Identifier: Apache-2.0
***********************************************************************/
declare module '@podman-desktop/api' {
/**
* Represents a reference to a command. Provides a title which
* will be used to represent a command in the UI and, optionally,
* an array of arguments which will be passed to the command handler
* function when invoked.
*/
export interface Command {
title: string;
command: string;
tooltip?: string;
// eslint-disable-next-line @typescript-eslint/no-explicit-any
arguments?: any[];
}
export interface MenuItem {
/**
* Unique within a single menu. Should be same as commandId for handler
*/
id: string;
type?: 'normal' | 'separator' | 'submenu' | 'checkbox' | 'radio';
label?: string;
icon?: string;
/**
* If false, the menu item will be greyed out and unclickable.
*/
enabled?: boolean;
/**
* If false, the menu item will be entirely hidden.
*/
visible?: boolean;
/**
* Should only be specified for `checkbox` or `radio` type menu items.
*/
checked?: boolean;
submenu?: MenuItem[];
}
export class Disposable {
constructor(func: () => void);
/**
* Creates a new Disposable calling the provided function
* on dispose.
* @param callOnDispose Function that disposes something.
*/
// eslint-disable-next-line @typescript-eslint/ban-types
constructor(callOnDispose: Function);
/**
* Dispose this object.
*/
dispose(): void;
static create(func: () => void): Disposable;
/**
* Combine many disposable-likes into one. Use this method
* when having objects with a dispose function which are not
* instances of Disposable.
*
* @param disposableLikes Objects that have at least a `dispose`-function member.
* @return Returns a new disposable which, upon dispose, will
* dispose all provided disposables.
*/
// eslint-disable-next-line @typescript-eslint/no-explicit-any
static from(...disposableLikes: { dispose: () => any }[]): Disposable;
}
/**
* Event to subscribe
*/
export interface Event<T> {
/**
* @param listener The listener function will be called when the event happens.
* @param thisArgs The `this`-argument which will be used when calling the event listener.
* @param disposables An array to which a {@link Disposable} will be added.
* @return A disposable which unsubscribes the event listener.
*/
// eslint-disable-next-line @typescript-eslint/no-explicit-any
(listener: (e: T) => any, thisArgs?: any, disposables?: Disposable[]): Disposable;
}
/**
* A class to create and manage an {@link Event} for clients to subscribe to.
* The emitter can only send one kind of event.
*
* Use this class to send events inside extension or provide API to the other
* extensions.
*/
export class EventEmitter<T> {
/**
* For the public to allow to subscribe to events from this Emitter
*/
event: Event<T>;
/**
* To fire an event to the subscribers
* @param event The event to send to the registered listeners
*/
fire(data: T): void;
/**
* Dispose by removing registered listeners
*/
dispose(): void;
}
export interface ExtensionContext {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
readonly subscriptions: { dispose(): any }[];
/**
* An absolute file path in which the extension can store state.
* The directory might not exist on disk and creation is
* up to the extension.
*/
readonly storagePath: string;
/**
* The uri of the directory containing the extension.
*/
readonly extensionUri: Uri;
}
/**
* A provider result represents the values a provider, like the {@linkcode ImageCheckerProvider},
* may return. For once this is the actual result type `T`, like `ImageChecks`, or a Promise that resolves
* to that type `T`. In addition, `null` and `undefined` can be returned - either directly or from a
* Promise.
*
* The snippets below are all valid implementations of the {@linkcode ImageCheckerProvider}:
*
* ```ts
* let a: ImageCheckerProvider = {
* check(image: ImageInfo, token?: CancellationToken): ProviderResult<ImageChecks> {
* return new ImageChecks();
* }
*
* let b: ImageCheckerProvider = {
* async check(image: ImageInfo, token?: CancellationToken): ProviderResult<ImageChecks> {
* return new ImageChecks();
* }
* }
*
* let c: ImageCheckerProvider = {
* check(image: ImageInfo, token?: CancellationToken): ProviderResult<ImageChecks> {
* return; // undefined
* }
* }
* ```
*/
export type ProviderResult<T> = T | undefined | Promise<T | undefined>;
export type ProviderStatus =
| 'not-installed'
| 'installed'
| 'configuring'
| 'configured'
| 'ready'
| 'started'
| 'stopped'
| 'starting'
| 'stopping'
| 'error'
| 'unknown';
export interface ProviderLifecycle {
initialize?(initContext: LifecycleContext): Promise<void>;
start(startContext: LifecycleContext): Promise<void>;
stop(stopContext: LifecycleContext): Promise<void>;
status(): ProviderStatus;
}
// For displaying essential information to the user
// "name" of the warning / title and a "details" field for more information
export interface ProviderInformation {
name: string;
details?: string;
}
export interface ProviderDetectionCheck {
name: string;
details?: string;
status: boolean;
}
export interface ProviderOptions {
id: string;
name: string;
status: ProviderStatus;
version?: string;
images?: ProviderImages;
links?: ProviderLinks[];
detectionChecks?: ProviderDetectionCheck[];
// Provide way to add additional warnings to the provider
warnings?: ProviderInformation[];
// Provide the message to display when the provider has no connections
emptyConnectionMarkdownDescription?: string;
}
export type ProviderConnectionStatus = 'started' | 'stopped' | 'starting' | 'stopping' | 'unknown';
export interface Logger {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
log(...data: any[]): void;
// eslint-disable-next-line @typescript-eslint/no-explicit-any
error(...data: any[]): void;
// eslint-disable-next-line @typescript-eslint/no-explicit-any
warn(...data: any[]): void;
}
export interface LifecycleContext {
log: Logger;
}
export interface ProviderConnectionLifecycle {
start?(startContext: LifecycleContext, logger?: Logger): Promise<void>;
stop?(stopContext: LifecycleContext, logger?: Logger): Promise<void>;
delete?(logger?: Logger): Promise<void>;
edit?(
editContext: LifecycleContext,
// eslint-disable-next-line @typescript-eslint/no-explicit-any
params: { [key: string]: any },
logger?: Logger,
token?: CancellationToken,
): Promise<void>;
}
export interface ContainerProviderConnectionEndpoint {
socketPath: string;
}
export interface ContainerProviderConnection {
name: string;
type: 'docker' | 'podman';
endpoint: ContainerProviderConnectionEndpoint;
lifecycle?: ProviderConnectionLifecycle;
status(): ProviderConnectionStatus;
}
export interface KubernetesProviderConnectionEndpoint {
apiURL: string;
}
export interface KubernetesProviderConnection {
name: string;
endpoint: KubernetesProviderConnectionEndpoint;
lifecycle?: ProviderConnectionLifecycle;
status(): ProviderConnectionStatus;
}
// common set of options for creating a provider
export interface ProviderConnectionFactory {
// Allow to initialize a provider
initialize?(): Promise<void>;
// Optional display name when creating the provider. For example 'Podman Machine' or 'Kind Cluster', etc.
creationDisplayName?: string;
// Optional button title when creating the provider. Default is 'Create new'.
creationButtonTitle?: string;
}
// create programmatically a ContainerProviderConnection
export interface ContainerProviderConnectionFactory extends ProviderConnectionFactory {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
create(params: { [key: string]: any }, logger?: Logger, token?: CancellationToken): Promise<void>;
}
// create a kubernetes provider
export interface KubernetesProviderConnectionFactory extends ProviderConnectionFactory {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
create?(params: { [key: string]: any }, logger?: Logger, token?: CancellationToken): Promise<void>;
}
export interface AuditRecord {
type: 'info' | 'warning' | 'error';
record: string;
}
export interface AuditResult {
records: AuditRecord[];
}
export interface AuditRequestItems {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
[key: string]: any;
}
export interface Auditor {
auditItems(items: AuditRequestItems): Promise<AuditResult>;
}
export interface Link {
title: string;
url: string;
group?: string;
}
export type CheckResultLink = Link;
export interface CheckResultFixCommand {
id: string;
title: string;
}
export interface CheckResult {
successful: boolean;
description?: string;
docLinksDescription?: string;
docLinks?: CheckResultLink[];
fixCommand?: CheckResultFixCommand;
}
export interface InstallCheck {
title: string;
execute(): Promise<CheckResult>;
init?(): Promise<void>;
}
export interface ProviderInstallation {
preflightChecks?(): InstallCheck[];
// ask to install the provider
install(logger: Logger): Promise<void>;
}
export interface ProviderUpdate {
version: string;
// ask to update the provider
update(logger: Logger): Promise<void>;
preflightChecks?(): InstallCheck[];
}
/**
* By providing this interface, when Podman Desktop is starting
* It'll start the provider through this interface.
* It can be turned off/on by the user.
*/
export interface ProviderAutostart {
start(logger: Logger): Promise<void>;
}
/**
* Allow to clean some resources in case for example
*/
export interface ProviderCleanup {
getActions(): Promise<ProviderCleanupAction[]>;
}
export interface ProviderCleanupExecuteOptions {
logger: Logger;
token?: CancellationToken;
}
// describe the action to perform
// for example, "remove a folder" or 'kill foo process'
export interface ProviderCleanupAction {
name: string;
// execute the action (can be canceled)
execute(options: ProviderCleanupExecuteOptions): Promise<void>;
}
export type ProviderLinks = Link;
export interface ProviderImages {
icon?: string | { light: string; dark: string };
logo?: string | { light: string; dark: string };
}
export interface Provider {
setContainerProviderConnectionFactory(
containerProviderConnectionFactory: ContainerProviderConnectionFactory,
connectionAuditor?: Auditor,
): Disposable;
setKubernetesProviderConnectionFactory(
containerProviderConnectionFactory: KubernetesProviderConnectionFactory,
connectionAuditor?: Auditor,
): Disposable;
registerContainerProviderConnection(connection: ContainerProviderConnection): Disposable;
registerKubernetesProviderConnection(connection: KubernetesProviderConnection): Disposable;
registerLifecycle(lifecycle: ProviderLifecycle): Disposable;
// register installation flow
registerInstallation(installation: ProviderInstallation): Disposable;
// register update flow
registerUpdate(update: ProviderUpdate): Disposable;
// register autostart flow
registerAutostart(autostart: ProviderAutostart): Disposable;
registerCleanup(cleanup: ProviderCleanup): Disposable;
dispose(): void;
readonly name: string;
readonly id: string;
readonly status: ProviderStatus;
updateStatus(status: ProviderStatus): void;
onDidUpdateStatus: Event<ProviderStatus>;
// version may not be defined
readonly version: string | undefined;
updateVersion(version: string): void;
onDidUpdateVersion: Event<string>;
readonly images: ProviderImages;
readonly links: ProviderLinks[];
// detection checks for the provider
readonly detectionChecks: ProviderDetectionCheck[];
// update the detection checks for the provider
// it may happen after an update or an installation
updateDetectionChecks(detectionChecks: ProviderDetectionCheck[]): void;
// update warning information for the provider
readonly warnings: ProviderInformation[];
updateWarnings(warnings: ProviderInformation[]): void;
// notify that detection checks have changed
onDidUpdateDetectionChecks: Event<ProviderDetectionCheck[]>;
}
export namespace commands {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
export function registerCommand(command: string, callback: (...args: any[]) => any, thisArg?: any): Disposable;
// eslint-disable-next-line @typescript-eslint/no-explicit-any
export function executeCommand<T = unknown>(command: string, ...rest: any[]): PromiseLike<T>;
}
export interface ProviderEvent {
id: string;
name: string;
status: ProviderStatus;
}
export interface UpdateContainerConnectionEvent {
providerId: string;
connection: ContainerProviderConnection;
status: ProviderConnectionStatus;
}
export interface UpdateKubernetesConnectionEvent {
providerId: string;
connection: KubernetesProviderConnection;
status: ProviderConnectionStatus;
}
export interface UnregisterContainerConnectionEvent {
providerId: string;
}
export interface UnregisterKubernetesConnectionEvent {
providerId: string;
}
export interface RegisterKubernetesConnectionEvent {
providerId: string;
}
export interface RegisterContainerConnectionEvent {
providerId: string;
connection: ContainerProviderConnection;
}
export interface ProviderContainerConnection {
providerId: string;
connection: ContainerProviderConnection;
}
export namespace provider {
export function createProvider(provider: ProviderOptions): Provider;
export const onDidUpdateProvider: Event<ProviderEvent>;
export const onDidUpdateContainerConnection: Event<UpdateContainerConnectionEvent>;
export const onDidUpdateKubernetesConnection: Event<UpdateKubernetesConnectionEvent>;
export const onDidUnregisterContainerConnection: Event<UnregisterContainerConnectionEvent>;
export const onDidRegisterContainerConnection: Event<RegisterContainerConnectionEvent>;
export function getContainerConnections(): ProviderContainerConnection[];
/**
* It returns the lifecycle context for the provider connection.
* If no context is found it throws an error
*
* @param providerId the provider id
* @param providerConnectionInfo the connection to retrieve the lifecycle context for
* @returns the lifecycle context
* @throws if no provider with the id has been found or there is no context associate to it.
*/
export function getProviderLifecycleContext(
providerId: string,
providerConnectionInfo: ProviderContainerConnectionInfo | ProviderKubernetesConnectionInfo,
): LifecycleContext;
}
export interface ProxySettings {
httpProxy: string | undefined;
httpsProxy: string | undefined;
noProxy: string | undefined;
}
export namespace proxy {
export function getProxySettings(): ProxySettings | undefined;
export function setProxy(proxySettings: ProxySettings): Promise<void>;
// Podman Desktop has updated the settings, propagates the changes to the provider.
export const onDidUpdateProxy: Event<ProxySettings>;
// The state of the proxy
export function isEnabled(): boolean;
export const onDidStateChange: Event<boolean>;
}
// An interface for "Default" registries that include the name, URL as well as an icon
// This allows an extension to "suggest" a registry to the user that you may
// login via a username & password.
export interface RegistrySuggestedProvider {
name: string;
url: string;
// Optional base64 PNG image (for transparency / non vector icons)
icon?: string;
}
export interface Registry extends RegistryCreateOptions {
source: string;
// Optional name and icon for the registry when it's being added (used for display within the UI)
name?: string;
icon?: string;
}
export interface RegistryCreateOptions {
serverUrl: string;
username: string;
secret: string;
insecure?: boolean;
}
export interface RegistryProvider {
readonly name: string;
create(registryCreateOptions: RegistryCreateOptions): Registry;
}
/**
* Handle registries from different sources
*/
export namespace registry {
export function registerRegistryProvider(registryProvider: RegistryProvider): Disposable;
// expose a registry from a source
export function registerRegistry(registry: Registry): Disposable;
// remove registry from a source
export function unregisterRegistry(registry: Registry): void;
// suggest a registry to be included on the registry settings page
export function suggestRegistry(registry: RegistrySuggestedProvider): Disposable;
export const onDidRegisterRegistry: Event<Registry>;
export const onDidUpdateRegistry: Event<Registry>;
export const onDidUnregisterRegistry: Event<Registry>;
}
export namespace tray {
/**
* Creates a menu not related to a Provider
* @param item the item to add in the tray menu
*/
export function registerMenuItem(item: MenuItem): Disposable;
/**
* Creates a menu in the tray for a given Provider
* @param providerId the same as the id on Provider provided by createProvider() method, need to place menu item properly
* @param item
*/
export function registerProviderMenuItem(providerId: string, item: MenuItem): Disposable;
}
export namespace configuration {
export function getConfiguration(section?: string, scope?: ConfigurationScope): Configuration;
/**
* An event that is emitted when the {@link Configuration configuration} changed.
*/
export const onDidChangeConfiguration: Event<ConfigurationChangeEvent>;
}
/**
* The configuration scope
*/
export type ConfigurationScope = string | ContainerProviderConnection | KubernetesProviderConnection;
export interface Configuration {
/**
* Return a value from this configuration.
*
* @param section Configuration name, supports _dotted_ names.
* @return The value `section` denotes or `undefined`.
*/
get<T>(section: string): T | undefined;
/**
* Return a value from this configuration.
*
* @param section Configuration name, supports _dotted_ names.
* @param defaultValue A value should be returned when no value could be found, is `undefined`.
* @return The value `section` denotes or the default.
*/
get<T>(section: string, defaultValue: T): T;
/**
* Check if this configuration has a certain value.
*
* @param section Configuration name, supports _dotted_ names.
* @return `true` if the section doesn't resolve to `undefined`.
*/
has(section: string): boolean;
/**
* Update a configuration value. The updated configuration values are persisted.
*/
// eslint-disable-next-line @typescript-eslint/no-explicit-any
update(section: string, value: any): Promise<void>;
/**
* Readable dictionary that backs this configuration.
*/
// eslint-disable-next-line @typescript-eslint/no-explicit-any
readonly [key: string]: any;
}
/**
* An event describing the change in Configuration
*/
export interface ConfigurationChangeEvent {
/**
* Checks if the given section has changed.
* If scope is provided, checks if the section has changed for resources under the given scope.
*
* @param section Configuration name, supports _dotted_ names.
* @param scope A scope in which to check.
* @return `true` if the given section has changed.
*/
affectsConfiguration(section: string, scope?: ConfigurationScope): boolean;
}
/**
* Defines a generalized way of reporting progress updates.
*/
export interface Progress<T> {
/**
* Report a progress update.
* @param value A progress item, like a message and/or an
* report on how much work finished
*/
report(value: T): void;
}
/**
* A location in the editor at which progress information can be shown. It depends on the
* location how progress is visually represented.
*/
export enum ProgressLocation {
/**
* Show progress bar under app icon in launcher bar.
*
* @deprecated This value is deprecated as it does not render equally on various supported platforms. It will be
* removed in future versions of Podman Desktop. We strongly encourage to use TASK_WIDGET instead.
* @see TASK_WIDGET
*/
APP_ICON = 1,
/**
* Show progress in the task manager widget
*/
TASK_WIDGET = 2,
}
/**
* Value-object describing where and how progress should show.
*/
export interface ProgressOptions {
/**
* The location at which progress should show.
*/
location: ProgressLocation;
/**
* A human-readable string which will be used to describe the
* operation.
*/
title?: string;
/**
* Controls if a cancel button should show to allow the user to
* cancel the long running operation. Note that currently only
* `ProgressLocation.Notification` is supporting to show a cancel
* button.
*/
cancellable?: boolean;
}
/**
* A cancellation token is passed to an asynchronous or long running
* operation to request cancellation.
*/
export interface CancellationToken {
/**
* Is `true` when the token has been cancelled, `false` otherwise.
*/
isCancellationRequested: boolean;
/**
* An {@link Event} which fires upon cancellation.
*/
// eslint-disable-next-line @typescript-eslint/no-explicit-any
onCancellationRequested: Event<any>;
}
export interface CancellationTokenSource {
/**
* The cancellation token of this source.
*/
token: CancellationToken;
/**
* Signal cancellation on the token.
*/
cancel(): void;
/**
* Dispose object and free resources.
*/
dispose(): void;
}
/**
* Impacts the behavior and appearance of the validation message.
*/
export enum InputBoxValidationSeverity {
Info = 1,
Warning = 2,
Error = 3,
}
/**
* Object to configure the behavior of the validation message.
*/
export interface InputBoxValidationMessage {
/**
* The validation message to display.
*/
readonly message: string;
/**
* The severity of the validation message.
* NOTE: When using `InputBoxValidationSeverity.Error`, the user will not be allowed to accept (hit ENTER) the input.
* `Info` and `Warning` will still allow the InputBox to accept the input.
*/
readonly severity: InputBoxValidationSeverity;
}
/**
* Options to configure the behavior of the input box UI.
*/
export interface InputBoxOptions {
/**
* An optional string that represents the title of the input box.
*/
title?: string;
/**
* The value to pre-fill in the input box.
*/
value?: string;
/**
* Selection of the pre-filled {@linkcode InputBoxOptions.value value}. Defined as tuple of two number where the
* first is the inclusive start index and the second the exclusive end index. When `undefined` the whole
* pre-filled value will be selected, when empty (start equals end) only the cursor will be set,
* otherwise the defined range will be selected.
*/
valueSelection?: [number, number];
/**
* The text to display underneath the input box.
*/
prompt?: string;
/**
* A description of the field to be show (Markdown format)
*/
markdownDescription?;
/**
* An optional string to show as placeholder in the input box to guide the user what to type.
*/
placeHolder?: string;
/**
* Controls if a password input is shown. Password input hides the typed text.
*/
password?: boolean;
/**
* Set to `true` to keep the input box open when focus moves to another part of the editor or to another window.
* This setting is ignored on iPad and is always false.
*/
ignoreFocusOut?: boolean;
/**
* Set to `true` when value represents a multi line content.
*/
multiline?: boolean;
/**
* An optional function that will be called to validate input and to give a hint
* to the user.
*
* @param value The current value of the input box.
* @return Either a human-readable string which is presented as an error message or an {@link InputBoxValidationMessage}
* which can provide a specific message severity. Return `undefined`, `null`, or the empty string when 'value' is valid.
*/
validateInput?(
value: string,
):
| string
| InputBoxValidationMessage
| undefined
| null
| Promise<string | InputBoxValidationMessage | undefined | null>;
}
/**
* The kind of {@link QuickPickItem quick pick item}.
*/
export enum QuickPickItemKind {
/**
* When a {@link QuickPickItem} has a kind of {@link Separator}, the item is just a visual separator and does not represent a real item.
* The only property that applies is {@link QuickPickItem.label label }. All other properties on {@link QuickPickItem} will be ignored and have no effect.
*/
Separator = -1,
/**
* The default {@link QuickPickItem.kind} is an item that can be selected in the quick pick.
*/
Default = 0,
}
/**
* Button for an action in a {@link QuickPick} or {@link InputBox}.
*/
export interface QuickInputButton {
/**
* Icon for the button.
*/
readonly iconPath: Uri | { light: Uri; dark: Uri };
/**
* An optional tooltip.
*/
readonly tooltip?: string;
}
/**
* Options to configure the behavior of the quick pick UI.
*/
export interface QuickPickOptions {
/**
* An optional string that represents the title of the quick pick.
*/
title?: string;
/**
* An optional flag to include the description when filtering the picks.
*/
matchOnDescription?: boolean;
/**
* An optional flag to include the detail when filtering the picks.
*/
matchOnDetail?: boolean;
/**
* An optional string to show as placeholder in the input box to guide the user what to pick on.
*/
placeHolder?: string;
/**
* Set to `true` to keep the picker open when focus moves to another part of the editor or to another window.
* This setting is ignored on iPad and is always false.
*/
ignoreFocusOut?: boolean;
/**
* An optional flag to make the picker accept multiple selections, if true the result is an array of picks.
*/
canPickMany?: boolean;
/**
* An optional function that is invoked whenever an item is selected.
*/
// eslint-disable-next-line @typescript-eslint/no-explicit-any
onDidSelectItem?(item: QuickPickItem | string): any;
}
/**
* Represents an item that can be selected from
* a list of items.
*/
export interface QuickPickItem {
/**
* A human-readable string which is rendered prominent. Supports rendering of {@link ThemeIcon theme icons} via
* the `$(<name>)`-syntax.
*/
label: string;
/**
* The kind of QuickPickItem that will determine how this item is rendered in the quick pick. When not specified,
* the default is {@link QuickPickItemKind.Default}.
*/
kind?: QuickPickItemKind;
/**
* A human-readable string which is rendered less prominent in the same line. Supports rendering of
* {@link ThemeIcon theme icons} via the `$(<name>)`-syntax.
*
* Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator}
*/
description?: string;
/**
* A human-readable string which is rendered less prominent in a separate line. Supports rendering of
* {@link ThemeIcon theme icons} via the `$(<name>)`-syntax.
*
* Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator}
*/
detail?: string;
/**
* Optional flag indicating if this item is picked initially. This is only honored when using
* the {@link window.showQuickPick showQuickPick()} API. To do the same thing with
* the {@link window.createQuickPick createQuickPick()} API, simply set the {@link QuickPick.selectedItems}
* to the items you want picked initially.
* (*Note:* This is only honored when the picker allows multiple selections.)
*
* @see {@link QuickPickOptions.canPickMany}
*
* Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator}
*/
picked?: boolean;
/**
* Always show this item.
*
* Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator}
*/
alwaysShow?: boolean;
/**
* Optional buttons that will be rendered on this particular item. These buttons will trigger
* an {@link QuickPickItemButtonEvent} when clicked. Buttons are only rendered when using a quickpick
* created by the {@link window.createQuickPick createQuickPick()} API. Buttons are not rendered when using
* the {@link window.showQuickPick showQuickPick()} API.
*
* Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator}
*/
buttons?: readonly QuickInputButton[];
}
/**
* Represents an item that can be selected from
* a list of items.
*/
export interface CustomPickSectionItem {
/**
* A human-readable string which is rendered prominent.
*/
title: string;
/**
* A human-readable string which is rendered in a separate line.
*/
content?: string;