1// Copyright (c) 2012 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5[
6  {
7    "namespace": "omnibox",
8    "description": "The omnibox API allows you to register a keyword with Google Chrome's address bar, which is also known as the omnibox.",
9    "types": [
10      {
11        "id": "DescriptionStyleType",
12        "type": "string",
13        "description": "The style type.",
14        "enum": ["url", "match", "dim"]
15      },
16      {
17        "id": "OnInputEnteredDisposition",
18        "type": "string",
19        "enum": ["currentTab", "newForegroundTab", "newBackgroundTab"],
20        "description": "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."
21      },
22      {
23        "id": "SuggestResult",
24        "type": "object",
25        "description": "A suggest result.",
26        "properties": {
27          "content": {
28            "type": "string",
29            "minLength": 1,
30            "description": "The text that is put into the URL bar, and that is sent to the extension when the user chooses this entry."
31          },
32          "description": {
33            "type": "string",
34            "minLength": 1,
35            "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. <dim><match>dimmed match</match></dim>. You must escape the five predefined entities to display them as text: stackoverflow.com/a/1091953/89484 "
36          },
37          "deletable": {
38            "type": "boolean",
39            "optional": true,
40            "description": "Whether the suggest result can be deleted by the user."
41          },
42          "descriptionStyles": {
43            "nodoc": true,
44            "optional": true,
45            "type": "array",
46            "description": "An array of style ranges for the description, as provided by the extension.",
47            "items": {
48              "type": "object",
49              "name": "matchClassification",
50              "description": "The style ranges for the description, as provided by the extension.",
51              "properties": {
52                "offset": { "type": "integer" },
53                "type": { "description": "The style type", "$ref": "DescriptionStyleType"},
54                "length": { "type": "integer", "optional": true }
55              }
56            }
57          },
58          "descriptionStylesRaw": {
59            "nodoc": true,
60            "optional": true,
61            "type": "array",
62            "description": "An array of style ranges for the description, as provided by ToValue().",
63            "items": {
64              "type": "object",
65              "name": "matchClassification",
66              "description": "The style ranges for the description, as provided by ToValue().",
67              "properties": {
68                "offset": { "type": "integer" },
69                "type": { "type": "integer" }
70              }
71            }
72          }
73        }
74      },
75      {
76        "id": "DefaultSuggestResult",
77        "inline_doc": true,
78        "type": "object",
79        "description": "A suggest result.",
80        "properties": {
81          "description": {
82            "type": "string",
83            "minLength": 1,
84            "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. <dim><match>dimmed match</match></dim>."
85          },
86          "descriptionStyles": {
87            "nodoc": true,
88            "optional": true,
89            "type": "array",
90            "description": "An array of style ranges for the description, as provided by the extension.",
91            "items": {
92              "type": "object",
93              "name": "matchClassification",
94              "description": "The style ranges for the description, as provided by the extension.",
95              "properties": {
96                "offset": { "type": "integer" },
97                "type": { "description": "The style type", "$ref": "DescriptionStyleType"},
98                "length": { "type": "integer", "optional": true }
99              }
100            }
101          },
102          "descriptionStylesRaw": {
103            "nodoc": true,
104            "optional": true,
105            "type": "array",
106            "description": "An array of style ranges for the description, as provided by ToValue().",
107            "items": {
108              "type": "object",
109              "name": "matchClassification",
110              "description": "The style ranges for the description, as provided by ToValue().",
111              "properties": {
112                "offset": { "type": "integer" },
113                "type": { "type": "integer" }
114              }
115            }
116          }
117        }
118      }
119    ],
120    "functions": [
121      {
122        "name": "sendSuggestions",
123        "nodoc": true,
124        "type": "function",
125        "description": "A callback passed to the onInputChanged event used for sending suggestions back to the browser.",
126        "parameters": [
127          {"type": "integer", "name": "requestId"},
128          {
129            "name": "suggestResults",
130            "type": "array",
131            "description": "An array of suggest results",
132            "items": {
133              "$ref": "SuggestResult"
134            }
135          }
136        ]
137      },
138      {
139        "name": "setDefaultSuggestion",
140        "type": "function",
141        "description": "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.",
142        "parameters": [
143          {
144            "name": "suggestion",
145            "$ref": "DefaultSuggestResult",
146            "description": "A partial SuggestResult object, without the 'content' parameter."
147          }
148        ]
149      }
150    ],
151    "events": [
152      {
153        "name": "onInputStarted",
154        "type": "function",
155        "description": "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.",
156        "parameters": []
157      },
158      {
159        "name": "onInputChanged",
160        "type": "function",
161        "description": "User has changed what is typed into the omnibox.",
162        "parameters": [
163          {
164            "type": "string",
165            "name": "text"
166          },
167          {
168            "name": "suggest",
169            "type": "function",
170            "description": "A callback passed to the onInputChanged event used for sending suggestions back to the browser.",
171            "parameters": [
172              {
173                "name": "suggestResults",
174                "type": "array",
175                "description": "Array of suggest results",
176                "items": {
177                  "$ref": "SuggestResult"
178                }
179              }
180            ]
181          }
182        ]
183      },
184      {
185        "name": "onInputEntered",
186        "type": "function",
187        "description": "User has accepted what is typed into the omnibox.",
188        "parameters": [
189          {
190            "type": "string",
191            "name": "text"
192          },
193          {
194            "name": "disposition",
195            "$ref": "OnInputEnteredDisposition"
196          }
197        ]
198      },
199      {
200        "name": "onInputCancelled",
201        "type": "function",
202        "description": "User has ended the keyword input session without accepting the input.",
203        "parameters": []
204      },
205      {
206        "name": "onDeleteSuggestion",
207        "type": "function",
208        "description": "User has deleted a suggested result.",
209        "parameters": [
210          {
211            "type": "string",
212            "name": "text",
213            "description": "Text of the deleted suggestion."
214          }
215        ]
216      }
217    ]
218  }
219]
220