From 00865591ac935cf3776e8b6b75d6a502341b5755 Mon Sep 17 00:00:00 2001 From: axel7083 <42176370+axel7083@users.noreply.github.com> Date: Mon, 29 Jan 2024 16:59:30 +0100 Subject: [PATCH] docs: adding withProgress api docs (#5736) * docs: adding withProgress api docs Signed-off-by: axel7083 <42176370+axel7083@users.noreply.github.com> * Update packages/extension-api/src/extension-api.d.ts Co-authored-by: Florent BENOIT Signed-off-by: axel7083 <42176370+axel7083@users.noreply.github.com> * Update packages/extension-api/src/extension-api.d.ts Co-authored-by: Florent BENOIT Signed-off-by: axel7083 <42176370+axel7083@users.noreply.github.com> --------- Signed-off-by: axel7083 <42176370+axel7083@users.noreply.github.com> Co-authored-by: Florent BENOIT --- packages/extension-api/src/extension-api.d.ts | 59 +++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/packages/extension-api/src/extension-api.d.ts b/packages/extension-api/src/extension-api.d.ts index d3446c0744ca..d5b61d265162 100644 --- a/packages/extension-api/src/extension-api.d.ts +++ b/packages/extension-api/src/extension-api.d.ts @@ -1507,6 +1507,65 @@ declare module '@podman-desktop/api' { */ export function showErrorMessage(message: string, ...items: string[]): Promise; + /** + * Show progress in Podman Desktop. Progress is shown while running the given callback + * and while the promise it returned isn't resolved nor rejected. The location at which + * progress should show (and other details) is defined via the passed {@linkcode ProgressOptions}. + * + * @param options the options for the task's details + * @param task A callback returning a promise. Progress state can be reported with + * the provided {@link Progress}-object. + * + * To report discrete progress, use `increment` to indicate how much work has been completed. Each call with + * a `increment` value will be summed up and reflected as overall progress until 100% is reached (a value of + * e.g. `10` accounts for `10%` of work done). + * Note that currently only `ProgressLocation.Notification` is capable of showing discrete progress. + * + * To monitor if the operation has been cancelled by the user, use the provided {@linkcode CancellationToken}. + * Note that currently only `ProgressLocation.Notification` is supporting to show a cancel button to cancel the + * long-running operation. + * + * @return The promise the task-callback returned. + * + * @example + * Here is a simple example + * ```ts + * await window.withProgress({ location: ProgressLocation.TASK_WIDGET, title: `Running task` }, + * async progress => { + * progress.report({message: 'task1' }); + * await task1(); + * progress.report({increment: 50, message: 'task2' }); + * await task2(); + * }, + * ); + * ``` + * @example + * The error is propagated if thrown inside the task callback. + * ```ts + * try { + * await window.withProgress( + * { location: ProgressLocation.TASK_WIDGET, title: `Running task` }, + * async progress => { + * throw new Error('error when running a task'); + * }, + * ); + * } catch (error) { + * // do something with the error + * } + * ``` + * + * @example + * You can return a value from the task callback + * ```ts + * const result: number = await window.withProgress( + * { location: ProgressLocation.TASK_WIDGET, title: `Running task` }, + * async progress => { + * // compute something + * return 55; + * }, + * ); + * ``` + */ export function withProgress( options: ProgressOptions, task: (progress: Progress<{ message?: string; increment?: number }>, token: CancellationToken) => Promise,