261 lines
10 KiB
TypeScript
261 lines
10 KiB
TypeScript
|
/**
|
||
|
|
* Namespace: browser.urlbar
|
||
|
|
* Generated from Mozilla sources. Do not manually edit!
|
||
|
|
*
|
||
|
|
* Use the <code>browser.urlbar</code> API to experiment with new features in the URLBar.
|
||
|
|
* Restricted to Mozilla privileged WebExtensions.
|
||
|
|
* Permissions: "urlbar"
|
||
|
|
*
|
||
|
|
* Comments found in source JSON schema files:
|
||
|
|
* This Source Code Form is subject to the terms of the Mozilla Public
|
||
|
|
* License, v. 2.0. If a copy of the MPL was not distributed with this
|
||
|
|
* file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
||
|
|
*/
|
||
|
|
import { Events } from "./events";
|
||
|
|
import { Types } from "./types";
|
||
|
|
|
||
|
|
export namespace Urlbar {
|
||
|
|
/**
|
||
|
|
* The state of an engagement made with the urlbar by the user. <code>start</code>: The user has started an engagement.
|
||
|
|
* <code>engagement</code>: The user has completed an engagement by picking a result. <code>abandonment</code>
|
||
|
|
* : The user has abandoned their engagement, for example by blurring the urlbar. <code>discard</code>
|
||
|
|
* : The engagement ended in a way that should be ignored by listeners.
|
||
|
|
*/
|
||
|
|
type EngagementState = "start" | "engagement" | "abandonment" | "discard";
|
||
|
|
|
||
|
|
/**
|
||
|
|
* A query performed in the urlbar.
|
||
|
|
*/
|
||
|
|
interface Query {
|
||
|
|
/**
|
||
|
|
* Whether the query's browser context is private.
|
||
|
|
*/
|
||
|
|
isPrivate: boolean;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The maximum number of results shown to the user.
|
||
|
|
*/
|
||
|
|
maxResults: number;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The query's search string.
|
||
|
|
*/
|
||
|
|
searchString: string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* List of acceptable source types to return.
|
||
|
|
*/
|
||
|
|
sources: SourceType[];
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* A result of a query. Queries can have many results. Each result is created by a provider.
|
||
|
|
*/
|
||
|
|
interface Result {
|
||
|
|
/**
|
||
|
|
* An object with arbitrary properties depending on the result's type.
|
||
|
|
*/
|
||
|
|
payload: ResultPayloadType;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The result's source.
|
||
|
|
*/
|
||
|
|
source: SourceType;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The result's type.
|
||
|
|
*/
|
||
|
|
type: ResultType;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Suggest a preferred position for this result within the result set.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
suggestedIndex?: number;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Possible types of results. <code>dynamic</code>: A result whose view and payload are specified by the extension. <code>
|
||
|
|
* remote_tab</code>: A synced tab from another device. <code>search</code>: A search suggestion from a search engine.
|
||
|
|
* <code>tab</code>: An open tab in the browser. <code>tip</code>: An actionable message to help the user with their query.
|
||
|
|
* <code>url</code>: A URL that's not one of the other types.
|
||
|
|
*/
|
||
|
|
type ResultType = "dynamic" | "remote_tab" | "search" | "tab" | "tip" | "url";
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Options to the <code>search</code> function.
|
||
|
|
*/
|
||
|
|
interface SearchOptions {
|
||
|
|
/**
|
||
|
|
* Whether to focus the input field and select its contents.
|
||
|
|
* Optional.
|
||
|
|
*/
|
||
|
|
focus?: boolean;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Possible sources of results. <code>bookmarks</code>: The result comes from the user's bookmarks. <code>history</code>
|
||
|
|
* : The result comes from the user's history. <code>local</code>: The result comes from some local source not covered by
|
||
|
|
* another source type. <code>network</code>: The result comes from some network source not covered by another source type.
|
||
|
|
* <code>search</code>: The result comes from a search engine. <code>tabs</code>: The result is an open tab in the browser
|
||
|
|
* or a synced tab from another device.
|
||
|
|
*/
|
||
|
|
type SourceType = "bookmarks" | "history" | "local" | "network" | "search" | "tabs";
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The behavior of the provider for the query.
|
||
|
|
*/
|
||
|
|
type OnBehaviorRequestedReturnEnum = "active" | "inactive" | "restricting";
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The payload of the result that was picked.
|
||
|
|
*/
|
||
|
|
interface OnResultPickedPayloadType {
|
||
|
|
[s: string]: unknown;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* An object with arbitrary properties depending on the result's type.
|
||
|
|
*/
|
||
|
|
interface ResultPayloadType {
|
||
|
|
[s: string]: unknown;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Before a query starts, this event is fired for the given provider. Its purpose is to request the provider's behavior for
|
||
|
|
* the query. The listener should return a behavior in response. By default, providers are inactive,
|
||
|
|
* so if your provider should always be inactive, you don't need to listen for this event.
|
||
|
|
*/
|
||
|
|
interface onBehaviorRequestedEvent extends Events.Event<(query: Query) => OnBehaviorRequestedReturnEnum> {
|
||
|
|
/**
|
||
|
|
* Registers an event listener <em>callback</em> to an event.
|
||
|
|
*
|
||
|
|
* @param callback Called when an event occurs. The parameters of this function depend on the type of event.
|
||
|
|
* @param providerName The name of the provider whose behavior the listener returns.
|
||
|
|
*/
|
||
|
|
addListener(callback: (query: Query) => OnBehaviorRequestedReturnEnum, providerName: string): void;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* This event is fired when the user starts and ends an engagement with the urlbar.
|
||
|
|
*/
|
||
|
|
interface onEngagementEvent extends Events.Event<(state: EngagementState) => void> {
|
||
|
|
/**
|
||
|
|
* Registers an event listener <em>callback</em> to an event.
|
||
|
|
*
|
||
|
|
* @param callback Called when an event occurs. The parameters of this function depend on the type of event.
|
||
|
|
* @param providerName The name of the provider that will listen for engagement events.
|
||
|
|
*/
|
||
|
|
addListener(callback: (state: EngagementState) => void, providerName: string): void;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* This event is fired for the given provider when a query is canceled. The listener should stop any ongoing fetch or
|
||
|
|
* creation of results and clean up its resources.
|
||
|
|
*/
|
||
|
|
interface onQueryCanceledEvent extends Events.Event<(query: Query) => void> {
|
||
|
|
/**
|
||
|
|
* Registers an event listener <em>callback</em> to an event.
|
||
|
|
*
|
||
|
|
* @param callback Called when an event occurs. The parameters of this function depend on the type of event.
|
||
|
|
* @param providerName The name of the provider that is creating results for the query.
|
||
|
|
*/
|
||
|
|
addListener(callback: (query: Query) => void, providerName: string): void;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* When a query starts, this event is fired for the given provider if the provider is active for the query and there are no
|
||
|
|
* other providers that are restricting. Its purpose is to request the provider's results for the query.
|
||
|
|
* The listener should return a list of results in response.
|
||
|
|
*/
|
||
|
|
interface onResultsRequestedEvent extends Events.Event<(query: Query) => Result[]> {
|
||
|
|
/**
|
||
|
|
* Registers an event listener <em>callback</em> to an event.
|
||
|
|
*
|
||
|
|
* @param callback Called when an event occurs. The parameters of this function depend on the type of event.
|
||
|
|
* @param providerName The name of the provider whose results the listener returns.
|
||
|
|
*/
|
||
|
|
addListener(callback: (query: Query) => Result[], providerName: string): void;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Typically, a provider includes a <code>url</code> property in its results' payloads.
|
||
|
|
* When the user picks a result with a URL, Firefox automatically loads the URL. URLs don't make sense for every result
|
||
|
|
* type, however. When the user picks a result without a URL, this event is fired. The provider should take an appropriate
|
||
|
|
* action in response. Currently the only applicable <code>ResultTypes</code> are <code>dynamic</code> and <code>tip</code>.
|
||
|
|
*/
|
||
|
|
interface onResultPickedEvent
|
||
|
|
extends Events.Event<(payload: OnResultPickedPayloadType, elementName: string) => void> {
|
||
|
|
/**
|
||
|
|
* Registers an event listener <em>callback</em> to an event.
|
||
|
|
*
|
||
|
|
* @param callback Called when an event occurs. The parameters of this function depend on the type of event.
|
||
|
|
* @param providerName The listener will be called for the results of the provider with this name.
|
||
|
|
*/
|
||
|
|
addListener(
|
||
|
|
callback: (payload: OnResultPickedPayloadType, elementName: string) => void,
|
||
|
|
providerName: string
|
||
|
|
): void;
|
||
|
|
}
|
||
|
|
|
||
|
|
interface Static {
|
||
|
|
/**
|
||
|
|
* Closes the urlbar view in the current window.
|
||
|
|
*/
|
||
|
|
closeView(): void;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Focuses the urlbar in the current window.
|
||
|
|
*
|
||
|
|
* @param select Optional. If true, the text in the urlbar will also be selected.
|
||
|
|
*/
|
||
|
|
focus(select?: boolean): void;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Starts a search in the urlbar in the current window.
|
||
|
|
*
|
||
|
|
* @param searchString The search string.
|
||
|
|
* @param options Optional. Options for the search.
|
||
|
|
*/
|
||
|
|
search(searchString: string, options?: SearchOptions): void;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Before a query starts, this event is fired for the given provider. Its purpose is to request the provider's behavior for
|
||
|
|
* the query. The listener should return a behavior in response. By default, providers are inactive,
|
||
|
|
* so if your provider should always be inactive, you don't need to listen for this event.
|
||
|
|
*/
|
||
|
|
onBehaviorRequested: onBehaviorRequestedEvent;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* This event is fired when the user starts and ends an engagement with the urlbar.
|
||
|
|
*/
|
||
|
|
onEngagement: onEngagementEvent;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* This event is fired for the given provider when a query is canceled. The listener should stop any ongoing fetch or
|
||
|
|
* creation of results and clean up its resources.
|
||
|
|
*/
|
||
|
|
onQueryCanceled: onQueryCanceledEvent;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* When a query starts, this event is fired for the given provider if the provider is active for the query and there are no
|
||
|
|
* other providers that are restricting. Its purpose is to request the provider's results for the query.
|
||
|
|
* The listener should return a list of results in response.
|
||
|
|
*/
|
||
|
|
onResultsRequested: onResultsRequestedEvent;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Typically, a provider includes a <code>url</code> property in its results' payloads.
|
||
|
|
* When the user picks a result with a URL, Firefox automatically loads the URL. URLs don't make sense for every result
|
||
|
|
* type, however. When the user picks a result without a URL, this event is fired. The provider should take an appropriate
|
||
|
|
* action in response. Currently the only applicable <code>ResultTypes</code> are <code>dynamic</code> and <code>tip</code>.
|
||
|
|
*/
|
||
|
|
onResultPicked: onResultPickedEvent;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Enables or disables the engagement telemetry.
|
||
|
|
*/
|
||
|
|
engagementTelemetry: Types.Setting;
|
||
|
|
}
|
||
|
|
}
|