From a9d6782e1d02dd6ebf0c8e2af12b06c9b7a95070 Mon Sep 17 00:00:00 2001 From: Lumen Date: Mon, 20 Oct 2025 19:11:15 +0300 Subject: [PATCH 1/2] Add SearchProvider2 and ResultMeta interfaces --- .../gnome-shell/src/extensions/global.d.ts | 115 ++++++++++++++++++ 1 file changed, 115 insertions(+) diff --git a/packages/gnome-shell/src/extensions/global.d.ts b/packages/gnome-shell/src/extensions/global.d.ts index 19a5d5a..469e104 100644 --- a/packages/gnome-shell/src/extensions/global.d.ts +++ b/packages/gnome-shell/src/extensions/global.d.ts @@ -1,5 +1,6 @@ import type Shell from '@girs/shell-17'; import type Clutter from '@girs/clutter-17'; +import type Gio from '@girs/gio-2.0'; declare global { /** * Global shell object created by GNOME Shell on startup. @@ -196,3 +197,117 @@ declare module '@girs/clutter-17/clutter-17' { } } } + +// #region SearchProvider2-Interface + +/** Contract interface between GNOME Shell and Shell extensions that implement + * a search provider. + * + * This interface defines the required methods and properties that must be + * implemented by any Shell extension to provide custom search functionality + * integrated with GNOME Shell's search system. + * + * [See Search Provider Implementation Example for more information](https://github.com/LumenGNU/ManSearchProvider) */ +export interface SearchProvider2 { + + /** Unique string identifier of the search provider in the system. */ + readonly id: string; + + /** The search provider's `GAppInfo`. */ + readonly appInfo: Gio.AppInfo | null; + + /** Controls the visibility of the "Show more results" action. */ + readonly canLaunchSearch: boolean; + + /** Handles Shell's request for an initial search and returns + * string identifiers of the found results. + * + * **NOTE**: The implementation **must** abort the search upon signal from the + * `cancellable` object. + * + * @param terms Array of search terms + * @param cancellable Object for cancelling the operation + * @returns Promise that resolves to an array of result identifiers */ + getInitialResultSet(terms: string[], cancellable: Gio.Cancellable): Promise; + + /** Handles Shell's request to refine search results when new + * search terms are added. + * + * Returns a subset of the original result set or the result of a new + * search. + * + * **NOTE**: The implementation **must** abort the search upon signal from the + * `cancellable` object. + * + * @param previousIdentifiers Result identifiers from the previous search + * @param terms Array of new search terms + * @param cancellable Object for cancelling the operation + * @returns Promise that resolves to an array of result identifiers */ + getSubsearchResultSet(previousIdentifiers: string[], terms: string[], cancellable: Gio.Cancellable): Promise; + + /** Handles Shell's request to reduce the number of displayed results + * for the current search. + * + * @param identifiers Complete list of current result identifiers + * @param maxResults Desired maximum number of results to display + * @returns Truncated array of result identifiers */ + filterResults(identifiers: string[], maxResults: number): string[]; + + /** Handles Shell's request to retrieve result metadata for display + * in the UI. + * + * **NOTE**: The implementation **must** abort processing upon signal from the + * `cancellable` object. + * + * @param identifiers List of identifiers + * @param cancellable Object for cancelling the operation + * @returns Promise that resolves to an array of metadata for each + * result from `identifiers` */ + getResultMetas(identifiers: string[], cancellable: Gio.Cancellable): Promise; + + /** Handles Shell's request to retrieve a custom widget for + * displaying the result. + * + * @param meta Result metadata + * @returns Custom widget or `null` for default rendering */ + createResultObject(meta: ResultMeta): Clutter.Actor | null; + + /** Handles Shell's request to activate a search result. + * + * @param identifier Identifier of the activated result + * @param terms Search terms that led to this result */ + activateResult(identifier: string, terms: string[]): void; + + /** Handles Shell's request to activate the "Show more results" action for + * current search terms. + * + * @param terms Current search terms */ + launchSearch(terms: string[]): void; +} + + +/** Search result metadata. + * + * Used by Shell to display search results. + * + * [See Search Provider Implementation Example for more information](https://github.com/LumenGNU/ManSearchProvider) */ +export interface ResultMeta { + + /** Unique identifier of the result */ + id: string; + + /** Name for the result (title) */ + name: string; + + /** Description of the result (optional). */ + description?: string; + + /** Text to place in the clipboard when the result is activated (optional). */ + clipboardText?: string; + + /** Callback function that returns an icon for the result at the specified size. */ + createIcon: (size: number) => Clutter.Actor; + +} + +// #endregion From 23bdc1d12b2dd084a996bf0daf29b29bbb4b32e7 Mon Sep 17 00:00:00 2001 From: Lumen Date: Tue, 21 Oct 2025 11:49:44 +0300 Subject: [PATCH 2/2] Add SearchProvider2 and ResultMeta interfaces to types module --- .../gnome-shell/src/extensions/global.d.ts | 116 +----------------- packages/gnome-shell/src/types/index.ts | 1 + .../gnome-shell/src/types/search-provider.ts | 111 +++++++++++++++++ 3 files changed, 113 insertions(+), 115 deletions(-) create mode 100644 packages/gnome-shell/src/types/search-provider.ts diff --git a/packages/gnome-shell/src/extensions/global.d.ts b/packages/gnome-shell/src/extensions/global.d.ts index 469e104..e353983 100644 --- a/packages/gnome-shell/src/extensions/global.d.ts +++ b/packages/gnome-shell/src/extensions/global.d.ts @@ -1,6 +1,6 @@ import type Shell from '@girs/shell-17'; import type Clutter from '@girs/clutter-17'; -import type Gio from '@girs/gio-2.0'; + declare global { /** * Global shell object created by GNOME Shell on startup. @@ -197,117 +197,3 @@ declare module '@girs/clutter-17/clutter-17' { } } } - -// #region SearchProvider2-Interface - -/** Contract interface between GNOME Shell and Shell extensions that implement - * a search provider. - * - * This interface defines the required methods and properties that must be - * implemented by any Shell extension to provide custom search functionality - * integrated with GNOME Shell's search system. - * - * [See Search Provider Implementation Example for more information](https://github.com/LumenGNU/ManSearchProvider) */ -export interface SearchProvider2 { - - /** Unique string identifier of the search provider in the system. */ - readonly id: string; - - /** The search provider's `GAppInfo`. */ - readonly appInfo: Gio.AppInfo | null; - - /** Controls the visibility of the "Show more results" action. */ - readonly canLaunchSearch: boolean; - - /** Handles Shell's request for an initial search and returns - * string identifiers of the found results. - * - * **NOTE**: The implementation **must** abort the search upon signal from the - * `cancellable` object. - * - * @param terms Array of search terms - * @param cancellable Object for cancelling the operation - * @returns Promise that resolves to an array of result identifiers */ - getInitialResultSet(terms: string[], cancellable: Gio.Cancellable): Promise; - - /** Handles Shell's request to refine search results when new - * search terms are added. - * - * Returns a subset of the original result set or the result of a new - * search. - * - * **NOTE**: The implementation **must** abort the search upon signal from the - * `cancellable` object. - * - * @param previousIdentifiers Result identifiers from the previous search - * @param terms Array of new search terms - * @param cancellable Object for cancelling the operation - * @returns Promise that resolves to an array of result identifiers */ - getSubsearchResultSet(previousIdentifiers: string[], terms: string[], cancellable: Gio.Cancellable): Promise; - - /** Handles Shell's request to reduce the number of displayed results - * for the current search. - * - * @param identifiers Complete list of current result identifiers - * @param maxResults Desired maximum number of results to display - * @returns Truncated array of result identifiers */ - filterResults(identifiers: string[], maxResults: number): string[]; - - /** Handles Shell's request to retrieve result metadata for display - * in the UI. - * - * **NOTE**: The implementation **must** abort processing upon signal from the - * `cancellable` object. - * - * @param identifiers List of identifiers - * @param cancellable Object for cancelling the operation - * @returns Promise that resolves to an array of metadata for each - * result from `identifiers` */ - getResultMetas(identifiers: string[], cancellable: Gio.Cancellable): Promise; - - /** Handles Shell's request to retrieve a custom widget for - * displaying the result. - * - * @param meta Result metadata - * @returns Custom widget or `null` for default rendering */ - createResultObject(meta: ResultMeta): Clutter.Actor | null; - - /** Handles Shell's request to activate a search result. - * - * @param identifier Identifier of the activated result - * @param terms Search terms that led to this result */ - activateResult(identifier: string, terms: string[]): void; - - /** Handles Shell's request to activate the "Show more results" action for - * current search terms. - * - * @param terms Current search terms */ - launchSearch(terms: string[]): void; -} - - -/** Search result metadata. - * - * Used by Shell to display search results. - * - * [See Search Provider Implementation Example for more information](https://github.com/LumenGNU/ManSearchProvider) */ -export interface ResultMeta { - - /** Unique identifier of the result */ - id: string; - - /** Name for the result (title) */ - name: string; - - /** Description of the result (optional). */ - description?: string; - - /** Text to place in the clipboard when the result is activated (optional). */ - clipboardText?: string; - - /** Callback function that returns an icon for the result at the specified size. */ - createIcon: (size: number) => Clutter.Actor; - -} - -// #endregion diff --git a/packages/gnome-shell/src/types/index.ts b/packages/gnome-shell/src/types/index.ts index 39db19c..5939a28 100644 --- a/packages/gnome-shell/src/types/index.ts +++ b/packages/gnome-shell/src/types/index.ts @@ -1,2 +1,3 @@ export * from './extension-metadata.js'; export * from './extension-object.js'; +export * from './search-provider.js'; diff --git a/packages/gnome-shell/src/types/search-provider.ts b/packages/gnome-shell/src/types/search-provider.ts new file mode 100644 index 0000000..767508d --- /dev/null +++ b/packages/gnome-shell/src/types/search-provider.ts @@ -0,0 +1,111 @@ +import type Gio from '@girs/gio-2.0'; +import type Clutter from '@girs/clutter-17'; + +/** Contract interface between GNOME Shell and Shell extensions that implement + * a search provider. + * + * This interface defines the required methods and properties that must be + * implemented by any Shell extension to provide custom search functionality + * integrated with GNOME Shell's search system. + * */ +export interface SearchProvider2 { + + /** Unique string identifier of the search provider in the system. */ + readonly id: string; + + /** The search provider's `GAppInfo`. */ + readonly appInfo: Gio.AppInfo | null; + + /** Controls the visibility of the "Show more results" action. */ + readonly canLaunchSearch: boolean; + + /** Handles Shell's request for an initial search and returns + * string identifiers of the found results. + * + * **NOTE**: The implementation **must** abort the search upon signal from the + * `cancellable` object. + * + * @param terms Array of search terms + * @param cancellable Object for cancelling the operation + * @returns Promise that resolves to an array of result identifiers */ + getInitialResultSet(terms: string[], cancellable: Gio.Cancellable): Promise; + + /** Handles Shell's request to refine search results when new + * search terms are added. + * + * Returns a subset of the original result set or the result of a new + * search. + * + * **NOTE**: The implementation **must** abort the search upon signal from the + * `cancellable` object. + * + * @param previousIdentifiers Result identifiers from the previous search + * @param terms Array of new search terms + * @param cancellable Object for cancelling the operation + * @returns Promise that resolves to an array of result identifiers */ + getSubsearchResultSet(previousIdentifiers: string[], terms: string[], cancellable: Gio.Cancellable): Promise; + + /** Handles Shell's request to reduce the number of displayed results + * for the current search. + * + * @param identifiers Complete list of current result identifiers + * @param maxResults Desired maximum number of results to display + * @returns Truncated array of result identifiers */ + filterResults(identifiers: string[], maxResults: number): string[]; + + /** Handles Shell's request to retrieve result metadata for display + * in the UI. + * + * **NOTE**: The implementation **must** abort processing upon signal from the + * `cancellable` object. + * + * @param identifiers List of identifiers + * @param cancellable Object for cancelling the operation + * @returns Promise that resolves to an array of metadata for each + * result from `identifiers` */ + getResultMetas(identifiers: string[], cancellable: Gio.Cancellable): Promise; + + /** Handles Shell's request to retrieve a custom widget for + * displaying the result. + * + * @param meta Result metadata + * @returns Custom widget or `null` for default rendering */ + createResultObject(meta: ResultMeta): Clutter.Actor | null; + + /** Handles Shell's request to activate a search result. + * + * @param identifier Identifier of the activated result + * @param terms Search terms that led to this result */ + activateResult(identifier: string, terms: string[]): void; + + /** Handles Shell's request to activate the "Show more results" action for + * current search terms. + * + * @param terms Current search terms */ + launchSearch(terms: string[]): void; +} + + +/** Search result metadata. + * + * Used by Shell to display search results. + * + * */ +export interface ResultMeta { + + /** Unique identifier of the result */ + id: string; + + /** Name for the result (title) */ + name: string; + + /** Description of the result (optional). */ + description?: string; + + /** Text to place in the clipboard when the result is activated (optional). */ + clipboardText?: string; + + /** Callback function that returns an icon for the result at the specified size. */ + createIcon: (size: number) => Clutter.Actor; + +}