src/chrome/common/extensions/api/omnibox.json

   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": "SuggestResult",
  12         "type": "object",
  13         "description": "A suggest result.",
  14         "properties": {
  15           "content": {
  16             "type": "string",
  17             "minLength": 1,
  18             "description": "The text that is put into the URL bar, and that is sent to the extension when the user chooses this entry."
  19           },
  20           "description": {
  21             "type": "string",
  22             "minLength": 1,
  23             "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>."
  24           },
  25           "descriptionStyles": {
  26             "nodoc": true,
  27             "optional": true,
  28             "type": "array",
  29             "description": "An array of style ranges for the description, as provided by the extension.",
  30             "items": {
  31               "type": "object",
  32               "name": "matchClassification",
  33               "description": "The style ranges for the description, as provided by the extension.",
  34               "properties": {
  35                 "offset": { "type": "integer" },
  36                 "type": { "description": "The style type", "type": "string", "enum": ["url", "match", "dim"]},
  37                 "length": { "type": "integer", "optional": true }
  38               }
  39             }
  40           },
  41           "descriptionStylesRaw": {
  42             "nodoc": true,
  43             "optional": true,
  44             "type": "array",
  45             "description": "An array of style ranges for the description, as provided by ToValue().",
  46             "items": {
  47               "type": "object",
  48               "name": "matchClassification",
  49               "description": "The style ranges for the description, as provided by ToValue().",
  50               "properties": {
  51                 "offset": { "type": "integer" },
  52                 "type": { "type": "integer" }
  53               }
  54             }
  55           }
  56         }
  57       },
  58       {
  59         "id": "DefaultSuggestResult",
  60         "inline_doc": true,
  61         "type": "object",
  62         "description": "A suggest result.",
  63         "properties": {
  64           "description": {
  65             "type": "string",
  66             "minLength": 1,
  67             "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>."
  68           },
  69           "descriptionStyles": {
  70             "nodoc": true,
  71             "optional": true,
  72             "type": "array",
  73             "description": "An array of style ranges for the description, as provided by the extension.",
  74             "items": {
  75               "type": "object",
  76               "name": "matchClassification",
  77               "description": "The style ranges for the description, as provided by the extension.",
  78               "properties": {
  79                 "offset": { "type": "integer" },
  80                 "type": { "description": "The style type", "type": "string", "enum": ["url", "match", "dim"]},
  81                 "length": { "type": "integer", "optional": true }
  82               }
  83             }
  84           },
  85           "descriptionStylesRaw": {
  86             "nodoc": true,
  87             "optional": true,
  88             "type": "array",
  89             "description": "An array of style ranges for the description, as provided by ToValue().",
  90             "items": {
  91               "type": "object",
  92               "name": "matchClassification",
  93               "description": "The style ranges for the description, as provided by ToValue().",
  94               "properties": {
  95                 "offset": { "type": "integer" },
  96                 "type": { "type": "integer" }
  97               }
  98             }
  99           }
 100         }
 101       }
 102     ],
 103     "functions": [
 104       {
 105         "name": "sendSuggestions",
 106         "nodoc": true,
 107         "type": "function",
 108         "description": "A callback passed to the onInputChanged event used for sending suggestions back to the browser.",
 109         "parameters": [
 110           {"type": "integer", "name": "requestId"},
 111           {
 112             "name": "suggestResults",
 113             "type": "array",
 114             "description": "An array of suggest results",
 115             "items": {
 116               "$ref": "SuggestResult"
 117             }
 118           }
 119         ]
 120       },
 121       {
 122         "name": "setDefaultSuggestion",
 123         "type": "function",
 124         "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.",
 125         "parameters": [
 126           {
 127             "name": "suggestion",
 128             "$ref": "DefaultSuggestResult",
 129             "description": "A partial SuggestResult object, without the 'content' parameter."
 130           }
 131         ]
 132       }
 133     ],
 134     "events": [
 135       {
 136         "name": "onInputStarted",
 137         "type": "function",
 138         "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.",
 139         "parameters": []
 140       },
 141       {
 142         "name": "onInputChanged",
 143         "type": "function",
 144         "description": "User has changed what is typed into the omnibox.",
 145         "parameters": [
 146           {
 147             "type": "string",
 148             "name": "text"
 149           },
 150           {
 151             "name": "suggest",
 152             "type": "function",
 153             "description": "A callback passed to the onInputChanged event used for sending suggestions back to the browser.",
 154             "parameters": [
 155               {
 156                 "name": "suggestResults",
 157                 "type": "array",
 158                 "description": "Array of suggest results",
 159                 "items": {
 160                   "$ref": "SuggestResult"
 161                 }
 162               }
 163             ]
 164           }
 165         ]
 166       },
 167       {
 168         "name": "onInputEntered",
 169         "type": "function",
 170         "description": "User has accepted what is typed into the omnibox.",
 171         "parameters": [
 172           {
 173             "type": "string",
 174             "name": "text"
 175           },
 176           {
 177             "name": "disposition",
 178             "type": "string",
 179             "enum": ["currentTab", "newForegroundTab", "newBackgroundTab"],
 180             "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."
 181           }
 182         ]
 183       },
 184       {
 185         "name": "onInputCancelled",
 186         "type": "function",
 187         "description": "User has ended the keyword input session without accepting the input.",
 188         "parameters": []
 189       }
 190     ]
 191   }
 192 ]