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": "devtools.panels",
8    "allowedContexts": ["devtools", "devtools_only"],
9    "defaultContexts": ["devtools", "devtools_only"],
10    "description": "Use the <code>chrome.devtools.panels</code> API to integrate your extension into Developer Tools window UI: create your own panels, access existing panels, and add sidebars.",
11    "nocompile": true,
12    "types": [
13      {
14        "id": "ElementsPanel",
15        "type": "object",
16        "description": "Represents the Elements panel.",
17        "events": [
18          {
19            "name": "onSelectionChanged",
20            "type": "function",
21            "description": "Fired when an object is selected in the panel."
22          }
23        ],
24        "functions": [
25          {
26            "name": "createSidebarPane",
27            "async": "callback",
28            "type": "function",
29            "description": "Creates a pane within panel's sidebar.",
30            "parameters": [
31              {
32                "name": "title",
33                "type": "string",
34                "description": "Text that is displayed in sidebar caption."
35              },
36              {
37                "name": "callback",
38                "type": "function",
39                "description": "A callback invoked when the sidebar is created.",
40                "optional": true,
41                "parameters": [
42                  {
43                    "name": "result",
44                    "description": "An ExtensionSidebarPane object for created sidebar pane.",
45                    "$ref": "ExtensionSidebarPane"
46                  }
47                ]
48              }
49            ]
50          }
51        ]
52      },
53      {
54        "id": "SourcesPanel",
55        "type": "object",
56        "description": "Represents the Sources panel.",
57        "events": [
58          {
59            "name": "onSelectionChanged",
60            "unsupported": true,
61            "description": "Fired when an object is selected in the panel."
62          }
63        ],
64        "functions": [
65          {
66            "name": "createSidebarPane",
67            "unsupported": true,
68            "type": "function",
69            "description": "Creates a pane within panel's sidebar.",
70            "parameters": [
71              {
72                "name": "title",
73                "type": "string",
74                "description": "Text that is displayed in sidebar caption."
75              },
76              {
77                "name": "callback",
78                "type": "function",
79                "description": "A callback invoked when the sidebar is created.",
80                "optional": true,
81                "parameters": [
82                  {
83                    "name": "result",
84                    "description": "An ExtensionSidebarPane object for created sidebar pane.",
85                    "$ref": "ExtensionSidebarPane"
86                  }
87                ]
88              }
89            ]
90          }
91        ]
92      },
93      {
94        "id": "ExtensionPanel",
95        "type": "object",
96        "description": "Represents a panel created by extension.",
97        "functions": [
98          {
99            "name": "createStatusBarButton",
100            "unsupported": true,
101            "description": "Appends a button to the status bar of the panel.",
102            "type": "function",
103            "parameters": [
104              {
105                "name": "iconPath",
106                "type": "string",
107                "description": "Path to the icon of the button. The file should contain a 64x24-pixel image composed of two 32x24 icons. The left icon is used when the button is inactive; the right icon is displayed when the button is pressed."
108              },
109              {
110                "name": "tooltipText",
111                "type": "string",
112                "description": "Text shown as a tooltip when user hovers the mouse over the button."
113              },
114              {
115                "name": "disabled",
116                "type": "boolean",
117                "description": "Whether the button is disabled."
118              }
119            ],
120            "returns": { "$ref": "Button" }
121          }
122        ],
123        "events": [
124          {
125            "name": "onSearch",
126            "unsupported": true,
127            "description": "Fired upon a search action (start of a new search, search result navigation, or search being canceled).",
128            "parameters": [
129              {
130                "name": "action",
131                "type": "string",
132                "description": "Type of search action being performed."
133              },
134              {
135                "name": "queryString",
136                "type": "string",
137                "optional": true,
138                "description": "Query string (only for 'performSearch')."
139              }
140            ]
141          },
142          {
143            "name": "onShown",
144            "type": "function",
145            "description": "Fired when the user switches to the panel.",
146            "parameters": [
147              {
148                "name": "window",
149                "type": "object",
150                "isInstanceOf": "global",
151                "additionalProperties": { "type": "any" },
152                "description": "The JavaScript <code>window</code> object of panel's page."
153              }
154            ]
155          },
156          {
157            "name": "onHidden",
158            "type": "function",
159            "description": "Fired when the user switches away from the panel."
160          }
161        ]
162      },
163      {
164        "id": "ExtensionSidebarPane",
165        "type": "object",
166        "description": "A sidebar created by the extension.",
167        "functions": [
168          {
169            "name": "setHeight",
170            "unsupported": true,
171            "type": "function",
172            "description": "Sets the height of the sidebar.",
173            "parameters": [
174              {
175                "name": "height",
176                "type": "string",
177                "description": "A CSS-like size specification, such as <code>'100px'</code> or <code>'12ex'</code>."
178              }
179            ]
180          },
181          {
182            "name": "setExpression",
183            "async": "callback",
184            "type": "function",
185            "description": "Sets an expression that is evaluated within the inspected page. The result is displayed in the sidebar pane.",
186            "parameters": [
187              {
188                "name": "expression",
189                "type": "string",
190                "description": "An expression to be evaluated in context of the inspected page. JavaScript objects and DOM nodes are displayed in an expandable tree similar to the console/watch."
191              },
192              {
193                "name": "rootTitle",
194                "type": "string",
195                "optional": true,
196                "description": "An optional title for the root of the expression tree."
197              },
198              {
199                "name": "callback",
200                "type": "function",
201                "optional": true,
202                "description": "A callback invoked after the sidebar pane is updated with the expression evaluation results."
203              }
204            ]
205          },
206          {
207            "name": "setObject",
208            "async": "callback",
209            "type": "function",
210            "description": "Sets a JSON-compliant object to be displayed in the sidebar pane.",
211            "parameters": [
212              {
213                "name": "jsonObject",
214                "type": "string",
215                "description": "An object to be displayed in context of the inspected page. Evaluated in the context of the caller (API client)."
216              },
217              {
218                "name": "rootTitle",
219                "type": "string",
220                "optional": true,
221                "description": "An optional title for the root of the expression tree."
222              },
223              {
224                "name": "callback",
225                "type": "function",
226                "optional": true,
227                "description": "A callback invoked after the sidebar is updated with the object."
228              }
229            ]
230          },
231          {
232            "name": "setPage",
233            "type": "function",
234            "async": true,
235            "description": "Sets an HTML page to be displayed in the sidebar pane.",
236            "parameters": [
237              {
238                "name": "path",
239                "$ref": "manifest.ExtensionURL",
240                "description": "Relative path of an extension page to display within the sidebar."
241              }
242            ]
243          }
244        ],
245        "events": [
246          {
247            "name": "onShown",
248            "type": "function",
249            "description": "Fired when the sidebar pane becomes visible as a result of user switching to the panel that hosts it.",
250            "parameters": [
251              {
252                "name": "window",
253                "type": "object",
254                "isInstanceOf": "global",
255                "additionalProperties": { "type": "any" },
256                "description": "The JavaScript <code>window</code> object of the sidebar page, if one was set with the <code>setPage()</code> method."
257              }
258            ]
259          },
260          {
261            "name": "onHidden",
262            "type": "function",
263            "description": "Fired when the sidebar pane becomes hidden as a result of the user switching away from the panel that hosts the sidebar pane."
264          }
265        ]
266      },
267      {
268        "id": "Button",
269        "type": "object",
270        "description": "A button created by the extension.",
271        "functions": [
272          {
273            "name": "update",
274            "unsupported": true,
275            "type": "function",
276            "description": "Updates the attributes of the button. If some of the arguments are omitted or <code>null</code>, the corresponding attributes are not updated.",
277            "parameters": [
278              {
279                "name": "iconPath",
280                "type": "string",
281                "optional": true,
282                "description": "Path to the new icon of the button."
283              },
284              {
285                "name": "tooltipText",
286                "type": "string",
287                "optional": true,
288                "description": "Text shown as a tooltip when user hovers the mouse over the button."
289              },
290              {
291                "name": "disabled",
292                "type": "boolean",
293                "optional": true,
294                "description": "Whether the button is disabled."
295              }
296            ]
297          }
298        ],
299        "events": [
300          {
301            "name": "onClicked",
302            "unsupported": true,
303            "type": "function",
304            "description": "Fired when the button is clicked."
305          }
306        ]
307      }
308    ],
309    "properties": {
310      "elements": {
311        "$ref": "ElementsPanel",
312        "description": "Elements panel."
313      },
314      "sources": {
315        "$ref": "SourcesPanel",
316        "description": "Sources panel."
317      },
318      "themeName": {
319        "type": "string",
320        "description": "The name of the current devtools theme."
321      }
322    },
323    "functions": [
324      {
325        "name": "create",
326        "type": "function",
327        "description": "Creates an extension panel.",
328        "async": "callback",
329        "parameters": [
330          {
331            "name": "title",
332            "type": "string",
333            "description": "Title that is displayed next to the extension icon in the Developer Tools toolbar."
334          },
335          {
336            "name": "iconPath",
337            "description": "Path of the panel's icon relative to the extension directory, or an empty string to use the default extension icon as the panel icon.",
338            "choices": [
339              {"type": "string", "enum": [""]},
340              {"$ref": "manifest.ExtensionURL"}
341            ]
342          },
343          {
344            "name": "pagePath",
345            "$ref": "manifest.ExtensionURL",
346            "description": "Path of the panel's HTML page relative to the extension directory."
347          },
348          {
349            "name": "callback",
350            "type": "function",
351            "optional": true,
352            "description": "A function that is called when the panel is created.",
353            "parameters": [
354              {
355                "name": "panel",
356                "description": "An ExtensionPanel object representing the created panel.",
357                "$ref": "ExtensionPanel"
358              }
359            ]
360          }
361        ]
362      },
363      {
364        "name": "setOpenResourceHandler",
365        "unsupported": true,
366        "type": "function",
367        "description": "Specifies the function to be called when the user clicks a resource link in the Developer Tools window. To unset the handler, either call the method with no parameters or pass null as the parameter.",
368        "async": "callback",
369        "parameters": [
370          {
371            "name": "callback",
372            "type": "function",
373            "optional": true,
374            "description": "A function that is called when the user clicks on a valid resource link in Developer Tools window. Note that if the user clicks an invalid URL or an XHR, this function is not called.",
375            "parameters": [
376              {
377                "name": "resource",
378                "$ref": "devtools.inspectedWindow.Resource",
379                "description": "A $(ref:devtools.inspectedWindow.Resource) object for the resource that was clicked."
380              }
381            ]
382          }
383        ]
384      },
385      {
386        "name": "openResource",
387        "unsupported": true,
388        "type": "function",
389        "description": "Requests DevTools to open a URL in a Developer Tools panel.",
390        "async": "callback",
391        "parameters": [
392          {
393            "name": "url",
394            "type": "string",
395            "description": "The URL of the resource to open."
396          },
397          {
398            "name": "lineNumber",
399            "type": "integer",
400            "description": "Specifies the line number to scroll to when the resource is loaded."
401          },
402          {
403            "name": "callback",
404            "type": "function",
405            "optional": true,
406            "description": "A function that is called when the resource has been successfully loaded."
407          }
408        ]
409      }
410    ],
411    "events": [
412      {
413        "name": "onThemeChanged",
414        "type": "function",
415        "description": "Fired when the devtools theme changes.",
416        "parameters": [
417          {
418            "name": "themeName",
419            "type": "string",
420            "description": "The name of the current devtools theme."
421          }
422        ]
423      }
424    ]
425  }
426]
427