whale.omnibox
| Description: | The omnibox API allows you to register a keyword with Google Chrome's address bar, which is also known as the omnibox. |
|---|---|
| Availability: | Since Chrome 20. |
| Manifest: | "omnibox": {...} |
{
"name": "Aaron's omnibox extension",
"version": "1.0",
**"omnibox": { "keyword" : "aaron" },**
**"icons": {**
**"16": "16-full-color.png"**
**},**
"background": {
"persistent": false,
"scripts": ["background.js"]
}
}
**Note:** Chrome automatically creates a grayscale version of your 16x16-pixel icon. You should provide a full-color version so that it can also be used in other situations that require color. For example, the [context menus API](contextMenus) also uses a 16x16-pixel icon, but it is displayed in color.
## Examples
You can find samples of this API on the [sample page](samples#search:omnibox).
## Types
### DescriptionStyleType
The style type.
| Enum |
|---|
| `"url"`, `"match"`, or `"dim"` |
### OnInputEnteredDisposition
The window disposition for the omnibox query. This is the recommended context to display results. For example, if the omnibox command is to navigate to a certain URL, a disposition of 'newForegroundTab' means the navigation should take place in a new selected tab.
| Enum |
|---|
| `"currentTab"`, `"newForegroundTab"`, or `"newBackgroundTab"` |
### SuggestResult
A suggest result.
| properties |
|---|
| string | content |
The text that is put into the URL bar, and that is sent to the extension when the user chooses this entry.
|
| string | description |
The text that is displayed in the URL dropdown. Can contain XML-style markup for styling. The supported tags are 'url' (for a literal URL), 'match' (for highlighting text that matched what the user's query), and 'dim' (for dim helper text). The styles can be nested, eg. dimmed match
## Methods
### setDefaultSuggestion
## Events
`whale.omnibox.setDefaultSuggestion(object suggestion)`
Sets the description and styling for the default suggestion. The default suggestion is the text that is displayed in the first suggestion row underneath the URL bar.
| Parameters |
|---|
| object | suggestion |
A partial SuggestResult object, without the 'content' parameter.
| string | description |
|---|---|
The text that is displayed in the URL dropdown. Can contain XML-style markup for styling. The supported tags are 'url' (for a literal URL), 'match' (for highlighting text that matched what the user's query), and 'dim' (for dim helper text). The styles can be nested, eg. dimmed match
### onInputStarted
User has started a keyword input session by typing the extension's keyword. This is guaranteed to be sent exactly once per input session, and before any onInputChanged events.
#### addListener
`whale.omnibox.onInputStarted.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function() {...};` |
### onInputChanged
User has changed what is typed into the omnibox.
#### addListener
`whale.omnibox.onInputChanged.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function(string text, function suggest) {...};`
| string | text | |
|---|---|---|
| function | suggest |
A callback passed to the onInputChanged event used for sending suggestions back to the browser.
The _suggest_ parameter should be a function that looks like this:
`function(array of [SuggestResult](/extensions/omnibox#type-SuggestResult) suggestResults) {...};`
| array of [SuggestResult](/extensions/omnibox#type-SuggestResult) | suggestResults |
|---|---|
Array of suggest results
|
|
|
### onInputEntered
User has accepted what is typed into the omnibox.
#### addListener
`whale.omnibox.onInputEntered.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function(string text, [OnInputEnteredDisposition](/extensions/omnibox#type-OnInputEnteredDisposition) disposition) {...};`
| string | text | |
|---|---|---|
| [OnInputEnteredDisposition](/extensions/omnibox#type-OnInputEnteredDisposition) | disposition |
Since Chrome 28.
|
|
### onInputCancelled
User has ended the keyword input session without accepting the input.
#### addListener
`whale.omnibox.onInputCancelled.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function() {...};` |
### onDeleteSuggestion
Since Chrome 63. _Warning:_ this is the current **Dev** channel. [Learn more](api_index#dev_apis).
User has deleted a suggested result.
#### addListener
`whale.omnibox.onDeleteSuggestion.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function(string text) {...};`
| string | text |
|---|---|
Text of the deleted suggestion.
|
|