└── BrowserAPI.md


/BrowserAPI.md:
--------------------------------------------------------------------------------
   1 | Mozilla Browser API
   2 | ===================
   3 | 
   4 | This document is an up-to-date and exhaustive description of the Mozilla Browser API.
   5 | 
   6 | The goal of this document is to eventually become a reference for implementations and documentation.
   7 | 
   8 | - [Summary](#Summary)
   9 | - [Usage](#Usage)
  10 | - [WebIDL](#WebIDL)
  11 | - [Methods](#Methods)
  12 | - [Events](#Events)
  13 | 
  14 | # <a name="Summary">Summary</a>
  15 | 
  16 | The HTML Browser API is an extension of the HTML `<iframe>` element that allows web apps to implement browsers or browser-like applications. This entails two major aspects:
  17 | 
  18 | - Make the iframe appear like a top-level browser window to the embedded content. This means that `window.top`, `window.parent`, `window.frameElement`, etc. should not reflect the frame hierarchy. Optionally, the notion that the embedded is an Open Web App can be expressed as well.
  19 | - An API to manipulate and listen for changes to the embedded content's state.
  20 | 
  21 | In addition to that, it's also possible to express the notion that the embedded content is an Open Web App. In that case the content is loaded within the appropriate app context (such as permissions).
  22 | 
  23 | # <a name="Usage">Usage</a>
  24 | 
  25 | An `<iframe>` is turned into a browser frame by setting the `mozbrowser` attribute:
  26 | 
  27 | ```html
  28 | <iframe src="http://hostname.tld" mozbrowser>`
  29 | ```
  30 | 
  31 | In order to embed an Open Web App, the `mozapp` attribute must also be supplied, with the path to the app's manifest:
  32 | 
  33 | ```html
  34 | <iframe src="http://hostname.tld" mozapp='http://path/to/manifest.webapp' mozbrowser>
  35 | ```
  36 | 
  37 | At last the content of the `<iframe>` can be loaded in its own child process, separate to the page embedding this frame by using the remote attribute.
  38 | 
  39 | ```html
  40 | <iframe src="http://hostname.tld" mozbrowser remote>
  41 | ```
  42 | 
  43 | ## <a name="WebIDL">WebIDL</a>
  44 | 
  45 | ``` webidl
  46 | callback BrowserElementNextPaintEventCallback = void ();
  47 | 
  48 | enum BrowserFindCaseSensitivity { "case-sensitive", "case-insensitive" };
  49 | enum BrowserFindDirection { "forward", "backward" };
  50 | 
  51 | dictionary BrowserElementDownloadOptions {
  52 |   DOMString? filename;
  53 |   DOMString? referrer;
  54 | };
  55 | 
  56 | dictionary BrowserElementExecuteScriptOptions {
  57 |   DOMString? url;
  58 |   DOMString? origin;
  59 | };
  60 | 
  61 | [NoInterfaceObject]
  62 | interface BrowserElement {
  63 | };
  64 | 
  65 | BrowserElement implements BrowserElementCommon;
  66 | BrowserElement implements BrowserElementPrivileged;
  67 | 
  68 | [NoInterfaceObject]
  69 | interface BrowserElementCommon {
  70 |   [Throws,
  71 |    Pref="dom.mozBrowserFramesEnabled",
  72 |    CheckAnyPermissions="browser embed-widgets"]
  73 |   void setVisible(boolean visible);
  74 | 
  75 |   [Throws,
  76 |    Pref="dom.mozBrowserFramesEnabled",
  77 |    CheckAnyPermissions="browser embed-widgets"]
  78 |   DOMRequest getVisible();
  79 | 
  80 |   [Throws,
  81 |    Pref="dom.mozBrowserFramesEnabled",
  82 |    CheckAnyPermissions="browser embed-widgets"]
  83 |   void setActive(boolean active);
  84 | 
  85 |   [Throws,
  86 |    Pref="dom.mozBrowserFramesEnabled",
  87 |    CheckAnyPermissions="browser embed-widgets"]
  88 |   boolean getActive();
  89 | 
  90 |   [Throws,
  91 |    Pref="dom.mozBrowserFramesEnabled",
  92 |    CheckAnyPermissions="browser embed-widgets"]
  93 |   void addNextPaintListener(BrowserElementNextPaintEventCallback listener);
  94 | 
  95 |   [Throws,
  96 |    Pref="dom.mozBrowserFramesEnabled",
  97 |    CheckAnyPermissions="browser embed-widgets"]
  98 |   void removeNextPaintListener(BrowserElementNextPaintEventCallback listener);
  99 | };
 100 | 
 101 | [NoInterfaceObject]
 102 | interface BrowserElementPrivileged {
 103 |   [Throws,
 104 |    Pref="dom.mozBrowserFramesEnabled",
 105 |    CheckAnyPermissions="browser"]
 106 |   void sendMouseEvent(DOMString type,
 107 |                       unsigned long x,
 108 |                       unsigned long y,
 109 |                       unsigned long button,
 110 |                       unsigned long clickCount,
 111 |                       unsigned long modifiers);
 112 | 
 113 |   [Throws,
 114 |    Pref="dom.mozBrowserFramesEnabled",
 115 |    Func="TouchEvent::PrefEnabled",
 116 |    CheckAnyPermissions="browser"]
 117 |   void sendTouchEvent(DOMString type,
 118 |                       sequence<unsigned long> identifiers,
 119 |                       sequence<long> x,
 120 |                       sequence<long> y,
 121 |                       sequence<unsigned long> rx,
 122 |                       sequence<unsigned long> ry,
 123 |                       sequence<float> rotationAngles,
 124 |                       sequence<float> forces,
 125 |                       unsigned long count,
 126 |                       unsigned long modifiers);
 127 | 
 128 |   [Throws,
 129 |    Pref="dom.mozBrowserFramesEnabled",
 130 |    CheckAnyPermissions="browser"]
 131 |   void goBack();
 132 | 
 133 |   [Throws,
 134 |    Pref="dom.mozBrowserFramesEnabled",
 135 |    CheckAnyPermissions="browser"]
 136 |   void goForward();
 137 | 
 138 |   [Throws,
 139 |    Pref="dom.mozBrowserFramesEnabled",
 140 |    CheckAnyPermissions="browser"]
 141 |   void reload(optional boolean hardReload = false);
 142 | 
 143 |   [Throws,
 144 |    Pref="dom.mozBrowserFramesEnabled",
 145 |    CheckAnyPermissions="browser"]
 146 |   void stop();
 147 | 
 148 |   [Throws,
 149 |    Pref="dom.mozBrowserFramesEnabled",
 150 |    CheckAnyPermissions="browser"]
 151 |   DOMRequest download(DOMString url,
 152 |                       optional BrowserElementDownloadOptions options);
 153 | 
 154 |   [Throws,
 155 |    Pref="dom.mozBrowserFramesEnabled",
 156 |    CheckAnyPermissions="browser"]
 157 |   DOMRequest purgeHistory();
 158 | 
 159 |   [Throws,
 160 |    Pref="dom.mozBrowserFramesEnabled",
 161 |    CheckAnyPermissions="browser"]
 162 |   DOMRequest getScreenshot([EnforceRange] unsigned long width,
 163 |                            [EnforceRange] unsigned long height,
 164 |                            optional DOMString mimeType="");
 165 | 
 166 |   [Throws,
 167 |    Pref="dom.mozBrowserFramesEnabled",
 168 |    CheckAnyPermissions="browser"]
 169 |   void zoom(float zoom);
 170 | 
 171 |   [Throws,
 172 |    Pref="dom.mozBrowserFramesEnabled",
 173 |    CheckAnyPermissions="browser"]
 174 |   DOMRequest getCanGoBack();
 175 | 
 176 |   [Throws,
 177 |    Pref="dom.mozBrowserFramesEnabled",
 178 |    CheckAnyPermissions="browser"]
 179 |   DOMRequest getCanGoForward();
 180 | 
 181 |   [Throws,
 182 |    Pref="dom.mozBrowserFramesEnabled",
 183 |    CheckAnyPermissions="browser"]
 184 |   DOMRequest getContentDimensions();
 185 | 
 186 |   [Throws,
 187 |    Pref="dom.mozBrowserFramesEnabled",
 188 |    CheckAllPermissions="browser input-manage"]
 189 |   DOMRequest setInputMethodActive(boolean isActive);
 190 | 
 191 |   [Throws,
 192 |    Pref="dom.mozBrowserFramesEnabled",
 193 |    CheckAllPermissions="browser nfc-manager"]
 194 |   void setNFCFocus(boolean isFocus);
 195 | 
 196 |   [Throws,
 197 |    Pref="dom.mozBrowserFramesEnabled",
 198 |    CheckAnyPermissions="browser"]
 199 |   void findAll(DOMString searchString, BrowserFindCaseSensitivity caseSensitivity);
 200 | 
 201 |   [Throws,
 202 |    Pref="dom.mozBrowserFramesEnabled",
 203 |    CheckAnyPermissions="browser"]
 204 |   void findNext(BrowserFindDirection direction);
 205 | 
 206 |   [Throws,
 207 |    Pref="dom.mozBrowserFramesEnabled",
 208 |    CheckAnyPermissions="browser"]
 209 |   void clearMatch();
 210 | 
 211 |   [Throws,
 212 |    Pref="dom.mozBrowserFramesEnabled",
 213 |    CheckAllPermissions="browser browser:universalxss"]
 214 |   DOMRequest executeScript(DOMString script,
 215 |                            optional BrowserElementExecuteScriptOptions options);
 216 | 
 217 | };
 218 | ```
 219 | 
 220 | ## <a name="DOMRequest">Note about `DOMRequest`</a>
 221 | 
 222 | The returned [DOMRequest](https://developer.mozilla.org/en-US/docs/Web/API/DOMRequest) objects can also be used as [Promise](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise).
 223 | 
 224 | For example:
 225 | 
 226 | ``` javascript
 227 | var req = iframe.getCanGoBack();
 228 | 
 229 | req.onsuccess = function() {
 230 |   if (req.result) {
 231 |     console.log("It's possible to navigate the history backward.");
 232 |   } else {
 233 |     console.log("It's not possible to navigate the history backward.");
 234 |   }
 235 | }
 236 | 
 237 | req.onerror = function() {
 238 |   console.error(error.name);
 239 | }
 240 | ```
 241 | 
 242 | Is equivalent to:
 243 | 
 244 | ``` javascript
 245 | iframe.getCanGoBack().then(result => {
 246 |   if (result) {
 247 |     console.log("It's possible to navigate the history backward.");
 248 |   } else {
 249 |     console.log("It's not possible to navigate the history backward.");
 250 |   }
 251 | }, error => console.error(error.name));
 252 | ```
 253 | 
 254 | # <a name="Methods">Methods</a>
 255 | 
 256 | ## <a name="goBack">The `goBack` method</a>
 257 | 
 258 | Requires permissions: **browser**.
 259 | 
 260 | ``` webidl
 261 | void goBack();
 262 | ```
 263 | 
 264 | ``` javascript
 265 | iframe.goBack();
 266 | ```
 267 | 
 268 | The [goBack](#goBack) method is used to navigate backwards in the browser iframe's history. By calling this method, the browser iframe changes its location for the previous location available in its navigation history, which sends the according events: [mozbrowserlocationchange](#mozbrowserlocationchange), [mozbrowserloadstart](#mozbrowserloadstart) and so on.
 269 | 
 270 | ## <a name="goForward">The `goForward` method</a>
 271 | 
 272 | Requires permissions: **browser**.
 273 | 
 274 | ``` webidl
 275 | void goForward();
 276 | ```
 277 | 
 278 | ``` javascript
 279 | iframe.goForward();
 280 | ```
 281 | 
 282 | The [goForward](#goForward) method is used to navigate forward in the browser iframe's history. By calling this method, the browser iframe changes its location for the next location available in its navigation history, which sends the according events: [mozbrowserlocationchange](#mozbrowserlocationchange), [mozbrowserloadstart](#mozbrowserloadstart) and so on. 
 283 | 
 284 | ## <a name="getCanGoBack">The `getCanGoBack` method</a>
 285 | 
 286 | Requires permissions: **browser**.
 287 | 
 288 | ``` webidl
 289 | DOMRequest getCanGoBack();
 290 | ```
 291 | 
 292 | ``` javascript
 293 | var req = iframe.getCanGoBack();
 294 | req.onsuccess = function() {
 295 |   if (req.result) {
 296 |     console.log("It's possible to navigate the history backward.");
 297 |   } else {
 298 |     console.log("It's not possible to navigate the history backward.");
 299 |   }
 300 | }
 301 | ```
 302 | 
 303 | The [getCanGoBack](#getCanGoBack) method is used to know if it's possible to go back in the navigation history of the browser iframe. Returns a [DOMRequest](https://developer.mozilla.org/en-US/docs/Web/API/DOMRequest) object to handle the request's success or error. If the request is successful, the request's result will be a boolean indicating if the history can be navigated backward (true) or not (false).
 304 | 
 305 | ## <a name="getCanGoForward">The `getCanGoForward` method</a>
 306 | 
 307 | Requires permissions: **browser**.
 308 | 
 309 | ``` webidl
 310 | DOMRequest getCanGoForward();
 311 | ```
 312 | 
 313 | ``` javascript
 314 | var req = iframe.getCanGoForward();
 315 | req.onsuccess = function() {
 316 |   if (req.result) {
 317 |     console.log("It's possible to navigate the history forward.");
 318 |   } else {
 319 |     console.log("It's not possible to navigate the history forward.");
 320 |   }
 321 | }
 322 | ```
 323 | 
 324 | The [getCanGoForward](#getCanGoForward) method is used to know if it's possible to go forward in the navigation history of the browser iframe. Returns a [DOMRequest](https://developer.mozilla.org/en-US/docs/Web/API/DOMRequest) object to handle the request's success or error. If the request is successful, the request's result will be a boolean indicating if the history can be navigated forward (true) or not (false).
 325 | 
 326 | ## <a name="reload">The `reload` method</a>
 327 | 
 328 | Requires permissions: **browser**.
 329 | 
 330 | ``` webidl
 331 | void reload(optional boolean hardReload = false);
 332 | ```
 333 | 
 334 | ``` javascript
 335 | iframe.reload();
 336 | ```
 337 | 
 338 | The [reload](#reload) method is used to reload the content of the iframe.
 339 | 
 340 | ## <a name="stop">The `stop` method</a>
 341 | 
 342 | Requires permissions: **browser**.
 343 | 
 344 | ``` webidl
 345 | void stop();
 346 | ```
 347 | 
 348 | ``` javascript
 349 | iframe.stop();
 350 | ```
 351 | 
 352 | The [stop](#stop) method is used to stop loading the content of the iframe.
 353 | 
 354 | ## <a name="purgeHistory">the `purgeHistory` method</a>
 355 | 
 356 | Requires permissions: **browser**.
 357 | 
 358 | ``` webidl
 359 | DOMRequest purgeHistory();
 360 | ```
 361 | 
 362 | ``` javascript
 363 | iframe.purgeHistory().then(_ => console.log("History cleared"));
 364 | ```
 365 | 
 366 | The [purgeHistory](#purgeHistory) method is used to clear the browsing history associated with the browser iframe. It doesn't delete cookies or offline web content; just the history data. It purges the older documents from history. Documents can be removed from session history for various reasons. For example to control memory usage of the browser, to prevent users from loading documents from history, to erase evidence of prior page loads etc…
 367 | 
 368 | ## <a name="zoom">the `zoom` method</a>
 369 | 
 370 | Requires permissions: **browser**.
 371 | 
 372 | ``` webidl
 373 | void zoom(float zoom);
 374 | ```
 375 | 
 376 | ``` javascript
 377 | iframe.zoom(1.2);
 378 | ```
 379 | 
 380 | Change the zoom factor of the browser iframe's content.
 381 | 
 382 | ## <a name="getContentDimensions">the `getContentDimensions` method</a>
 383 | 
 384 | Requires permissions: **browser**.
 385 | 
 386 | ``` webidl
 387 | DOMRequest getContentDimensions();
 388 | ```
 389 | 
 390 | ``` javascript
 391 | var req = iframe.getContentDimensions();
 392 | req.onsuccess = function() {
 393 |   console.log("page size:", req.result.width + "x" + req.result.height);
 394 | }
 395 | ```
 396 | 
 397 | Get the size of the content window. Equivalent of `document.body.scrollWidth` and `document.body.scrollHeight`.
 398 | 
 399 | ## <a name="findAll">the `findAll` method</a>
 400 | 
 401 | Requires permissions: **browser**.
 402 | 
 403 | ``` webidl
 404 | void findAll(DOMString searchString, BrowserFindCaseSensitivity caseSensitivity);
 405 | ```
 406 | 
 407 | ``` javascript
 408 | iframe.findAll("Foo", "case-sensitive");
 409 | ```
 410 | 
 411 | Search for a string in a page. The first instance of the string, relative to the caret position, will be highlighted. This will be followed by a [mozbrowserfindchange](#mozbrowserfindchange) event, carrying details about the search results. [findNext](#findNext) can be used to highlight the next or previous result.
 412 | 
 413 | ## <a name="findNext">the `findNext` method</a>
 414 | 
 415 | Requires permissions: **browser**.
 416 | 
 417 | ``` webidl
 418 | void findNext(BrowserFindDirection direction);
 419 | ```
 420 | 
 421 | ``` javascript
 422 | iframe.findNext("backward");
 423 | ```
 424 | 
 425 | Highlight the next or previous search result. Followed by a [mozbrowserfindchange](#mozbrowserfindchange)  event.
 426 | 
 427 | ## <a name="clearMatch">the `clearMatch` method</a>
 428 | 
 429 | Requires permissions: **browser**.
 430 | 
 431 | ``` webidl
 432 | void clearMatch();
 433 | ```
 434 | 
 435 | ``` javascript
 436 | iframe.clearMatch();
 437 | ```
 438 | 
 439 | Clear text highlighted via the [findAll](#findAll) and [findNext](#findNext) methods. Followed by a [mozbrowserfindchange](#mozbrowserfindchange) event.
 440 | 
 441 | ## <a name="setVisible">the `setVisible` method</a>
 442 | 
 443 | Requires permissions: **browser** or **embed-widgets**.
 444 | 
 445 | ``` webidl
 446 | void setVisible(boolean visible);
 447 | ```
 448 | 
 449 | ``` javascript
 450 | iframe.setVisible(true);
 451 | ```
 452 | 
 453 | Gecko implementation note: equivalent to `nsIDocShell.isActive`.
 454 | 
 455 | The [setVisible](#setVisible) method is used to change the visibility state of the browser iframe.
 456 | 
 457 | The visible state of a browser iframe has nothing to do with its actual visibility (which is handled through CSS). The visible state is used to define the level of resources required by the browser iframe. If the visible state is set to true, it means that the browser iframe has a high priority on the resources needed to render and handle its content. On the contrary, if its visible state is set to false, the browser has a low priority over the resources it needs.
 458 | 
 459 | As an example, if the content of a browser iframe uses the `window.requestAnimationFrame` method and if the visible state is set to true, `window.requestAnimationFrame` will be called as often as necessary. However, if the visible state is set to false, `window.requestAnimationFrame` will be called only when there are free resources to do it.
 460 | 
 461 | Changing the visibility of the iframe will trigger a [mozbrowservisibilitychange](#mozbrowservisibilitychange) event.
 462 | 
 463 | ## <a name="getVisible">the `getVisible` method</a>
 464 | 
 465 | Requires permissions: **browser** or **embed-widgets**.
 466 | 
 467 | ``` webidl
 468 | DOMRequest getVisible();
 469 | ```
 470 | 
 471 | ``` webidl
 472 | var req = iframe.getVisible();
 473 | req.onsuccess = function() {
 474 |   if (req.result) {
 475 |     console.log("Iframe visibility is set to true");
 476 |   } else {
 477 |     console.log("Iframe visibility is set to false");
 478 |   }
 479 | }
 480 | ```
 481 | 
 482 | The [getVisible](#getVisible) method is used to request the current visibility state of the browser iframe. See [setVisible](#setVisible).
 483 | 
 484 | ## <a name="setActive">the `setActive` method</a>
 485 | 
 486 | Requires permissions: **browser** or **embed-widgets**.
 487 | 
 488 | ``` webidl
 489 | void setActive(boolean active);
 490 | ```
 491 | 
 492 | Gecko implementation note: equivalent to setting `nsIFrameLoader.visible`.
 493 | 
 494 | This helps the process manager prioritize processes.
 495 | 
 496 | ## <a name="getActive">the `getActive` method</a>
 497 | 
 498 | Requires permissions: **browser** or **embed-widgets**.
 499 | 
 500 | ``` webidl
 501 | boolean getActive();
 502 | ```
 503 | 
 504 | See [setActive](#setActive).
 505 | 
 506 | ## <a name="addNextPaintListener">the `addNextPaintListener` method</a>
 507 | 
 508 | Requires permissions: **browser** or **embed-widgets**.
 509 | 
 510 | ``` webidl
 511 | void addNextPaintListener(BrowserElementNextPaintEventCallback listener);
 512 | ```
 513 | 
 514 | ``` javascript
 515 | function onNextPaint() {
 516 |   console.log("paint");
 517 | }
 518 | iframe.addNextPaintListener(onNextPaint);
 519 | ```
 520 | 
 521 | The listener is called when content of the iframe is repainted on the screen. The event provides information about what has been repainted. It is mainly used to investigate performance optimization.
 522 | 
 523 | ## <a name="removeNextPaintListener">the `removeNextPaintListener` method</a>
 524 | 
 525 | Requires permissions: **browser** or **embed-widgets**.
 526 | 
 527 | ``` webidl
 528 | void removeNextPaintListener(BrowserElementNextPaintEventCallback listener);
 529 | ```
 530 | 
 531 | ``` javascript
 532 | iframe.removeNextPaintListener(onNextPaint);
 533 | ```
 534 | 
 535 | Remove previously added paint listener. See [addNextPaintListener](#addNextPaintListener).
 536 | 
 537 | ## <a name="sendMouseEvent">The `sendMouseEvent` method</a>
 538 | 
 539 | Requires permissions: **browser**.
 540 | 
 541 | ``` webidl
 542 | void sendMouseEvent(DOMString type, unsigned long x, unsigned long y, unsigned long button, unsigned long clickCount, unsigned long modifiers);
 543 | ```
 544 | 
 545 | ``` javascript
 546 | iframe.sendMouseEvent("mousemove", x, y, 0, 0, 0)
 547 | iframe.sendMouseEvent("mousedown", x, y, 0, 1, 0)
 548 | iframe.sendMouseEvent("mouseup", x, y, 0, 1, 0)
 549 | ```
 550 | 
 551 | The sendMouseEvent method allows to fake a mouse event and send it to the browser iframe's content.
 552 | 
 553 | ### Parameters:
 554 | 
 555 | - type: A string representing the event type. Possible values are mousedown, mouseup, mousemove, mouseover, mouseout, or contextmenu.
 556 | - x: A number representing the x position of the cursor relative to the browser iframe's visible area in CSS pixels.
 557 | - y: A number representing the y position of the cursor relative to the browser iframe's visible area in CSS pixels.
 558 | - button: A number representing which button has been pressed on the mouse: 0 (Left button), 1 (middle button), or 2 (right button).
 559 | - clickCount: Number of clicks that have been performed.
 560 | - modifiers: A number representing a key pressed at the same time the mouse button was clicked:
 561 |   - 1 : The ALT key
 562 |   - 2 : The CONTROL key
 563 |   - 4 : The SHIFT key
 564 |   - 8 : The META key
 565 |   - 16 : The ALTGRAPH key
 566 |   - 32 : The CAPSLOCK key
 567 |   - 64 : The FN key
 568 |   - 128 : The NUMLOCK key
 569 |   - 256 : The SCROLL key
 570 |   - 512 : The SYMBOLLOCK key
 571 |   - 1024 : The WIN key
 572 | 
 573 | For example, to send WIN and ALT modifiers, use `1 | 1014`.
 574 | 
 575 | ## <a name="sendTouchEvent">The `sendTouchEvent` method</a>
 576 | 
 577 | Requires permissions: **browser**.
 578 | 
 579 | ``` webidl
 580 | void sendTouchEvent(DOMString type, sequence<unsigned long> identifiers, sequence<long> x, sequence<long> y, sequence<unsigned long> rx, sequence<unsigned long> ry, sequence<float> rotationAngles, sequence<float> forces, unsigned long count, unsigned long modifiers);
 581 | ```
 582 | 
 583 | ``` javascript
 584 | iframe.sendTouchEvent("touchstart", [1], [x], [y], [2], [2], [20], [0.5], 1, 0);
 585 | ```
 586 | 
 587 | The sendTouchEvent method allows to fake a touch event and send it to the browser iframe's content.
 588 | 
 589 | Note: This method is available for touch enable devices only.
 590 | 
 591 | Parameters:
 592 | 
 593 | - type: A string representing the event type. Possible values are `touchstart`, `touchend`, `touchmove`, or `touchcancel`.
 594 | - x: An array of numbers representing the x position of each touch point relative to the browser iframe's visible area in CSS pixels.
 595 | - y: An array of numbers representing the y position of each touch point relative to the browser iframe's visible area in CSS pixels.
 596 | - rx: An array of numbers representing the x radius of each touch point in CSS pixels.
 597 | - ry: An array of numbers representing the y radius of each touch point in CSS pixels.
 598 | - rotationAngles: An array of numbers representing the angle of each touch point in degrees.
 599 | - forces: An array of numbers representing the intensity of each touch in the range [0,1].
 600 | - count: Number of touches that have been performed.
 601 | - modifiers: A number representing a key pressed at the same time the touches were performed:
 602 |   - 1 : The ALT key
 603 |   - 2 : The CONTROL key
 604 |   - 4 : The SHIFT key
 605 |   - 8 : The META key
 606 |   - 16 : The ALTGRAPH key
 607 |   - 32 : The CAPSLOCK key
 608 |   - 64 : The FN key
 609 |   - 128 : The NUMLOCK key
 610 |   - 256 : The SCROLL key
 611 |   - 512 : The SYMBOLLOCK key
 612 |   - 1024 : The WIN key
 613 | 
 614 | For example, to send WIN and ALT modifiers, use `1 | 1014`.
 615 | 
 616 | ## <a name="download">The `download` method</a>
 617 | 
 618 | Requires permissions: **browser**.
 619 | 
 620 | ``` webidl
 621 | DOMRequest download(DOMString url, optional BrowserElementDownloadOptions options);
 622 | ```
 623 | 
 624 | ``` javascript
 625 | var req = iframe.download(fooURL, { filename: 'foo.bin' });
 626 | req.onsuccess = function() {
 627 |   console.log("File downladed");
 628 | }
 629 | req.onerror = function() {
 630 |   console.log("Download error");
 631 | }
 632 | ```
 633 | 
 634 | Download specified URL to specified filename.
 635 | 
 636 | ## <a name="getScreenshot">The `getScreenshot` method</a>
 637 | 
 638 | Requires permissions: **browser**.
 639 | 
 640 | ``` webidl
 641 | DOMRequest getScreenshot([EnforceRange] unsigned long maxWidth, [EnforceRange] unsigned long maxHeight, optional DOMString mimeType="");
 642 | ```
 643 | 
 644 | ``` javascript
 645 | var req = iframe.getScreenshot(100, 100);
 646 | req.onsuccess = function() {
 647 |   var blob = req.result;
 648 |   var url = URL.createObjectURL(blob);
 649 | }
 650 | ```
 651 | 
 652 | The [getScreenshot](#getScreenshot) method lets you request a screenshot of an iframe, scaled to fit within a specified maximum width and height; the image may be cropped if necessary but will not be squished vertically or horizontally. MIME type specifying the format of the image to be returned; the default is `image/jpeg`. Use `image/png` to capture the alpha channel of the rendering result by returning a PNG-format image. This lets you get the transparent background of the iframe.
 653 | 
 654 | 
 655 | [getScreenshot](#getScreenshot) waits for the event loop to go idle before it takes the screenshot. It won't wait more than 2000ms (Gecko implementation note: delay defined by the `dom.browserElement.maxScreenshotDelayMS` preference).
 656 | 
 657 | ## <a name="executeScript">The `executeScript` method</a>
 658 | 
 659 | Requires permissions: **browser** and **browser:universalxss**.
 660 | 
 661 | ``` webidl
 662 | DOMRequest executeScript(DOMString script, optional BrowserElementExecuteScriptOptions options);
 663 | ```
 664 | 
 665 | ``` javascript
 666 | var req1 = iframe.executeScript(`
 667 |   var a = 3;
 668 |   a + 3
 669 | `, {url: 'http://example.com/index.html'});
 670 | 
 671 | req1.onsuccess = function() {
 672 |   console.log(req1.result); // 6
 673 | }
 674 | 
 675 | var req2 = iframe.executeScript(`
 676 |   new Promise((resolve, reject) => {
 677 |     setTimeout(function() {
 678 |       resolve(6);
 679 |     }, 1000})
 680 |   )
 681 | `, {origin: 'http://example.com'});
 682 | 
 683 | req2.onsuccess = function() {
 684 |   console.log(req2.result); // 6
 685 | }
 686 | 
 687 | ```
 688 | 
 689 | If the script value is a not a [Promise](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise), it is simply return as the request value. If the script value is a Promise, the result of the request will be the Promise resolved value.
 690 | 
 691 | The `url` or `origin` option is required to ensure the script is being executed in the expected context.
 692 | 
 693 | ## <a name="setInputMethodActive">The `setInputMethodActive` method</a>
 694 | 
 695 | Requires permissions: **browser** and **input-manager**.
 696 | 
 697 | ``` webidl
 698 | DOMRequest setInputMethodActive(boolean isActive);
 699 | ```
 700 | 
 701 | ``` javascript
 702 | iframe.setInputMethodActive(true);
 703 | ```
 704 | 
 705 | Calling [setInputMethodActive](#setInputMethodActive) on an iframe will set it as active IME window and other iframes as non-active IME windows. Useful when a top level app wants to activate a window (one at a time) as a IME (Input Method Editor, like a keyboard).
 706 | 
 707 | ## <a name="setNFCFocus">The `setNFCFocus` method</a>
 708 | 
 709 | Requires permissions: **browser** and **nfc-manager**.
 710 | 
 711 | ``` webidl
 712 | void setNFCFocus(boolean isFocus);
 713 | ```
 714 | 
 715 | ``` javascript
 716 | iframe.setNFCFocus(true);
 717 | ```
 718 | 
 719 | Sets whether an iframe will receive NFC events.
 720 | 
 721 | # <a name="Events">Events</a>
 722 | 
 723 | Most of the events come with with a `details` property which carry extra information about the event.
 724 | 
 725 | ## <a name="mozbrowserloadstart">The `mozbrowserloadstart` event</a>
 726 | 
 727 | Sent when the browser iframe starts to load a new page. This is usually when the embedder wants to start spinning a loading indicator.
 728 | 
 729 | ## <a name="mozbrowserloadend">The `mozbrowserloadend` event</a>
 730 | 
 731 | Sent when the browser iframe has finished loading all its assets, or failed to load. This is usually when the embedder wants to stop spinning a loading indicator.
 732 | 
 733 | ``` javascript
 734 | event.details = {
 735 |   backgroundColor: String
 736 | }
 737 | ```
 738 | 
 739 | ## <a name="mozbrowsertitlechange">The `mozbrowsertitlechange` event</a>
 740 | 
 741 | Sent when the top level window title changed.
 742 | 
 743 | ``` javascript
 744 |   event.details = String;
 745 | ```
 746 | 
 747 | ## <a name="mozbrowservisibilitychange">The `mozbrowservisibilitychange` event</a>
 748 | 
 749 | Sent when the visibility state of the iframe changed. See also [setVisible](#setVisible).
 750 | 
 751 | ``` javascript
 752 |   event.details = {
 753 |     visible: Boolean
 754 |   }
 755 | ```
 756 | 
 757 | ## <a name="mozbrowserfirstpaint">The `mozbrowserfirstpaint` event</a>
 758 | 
 759 | Sent when the iframe paints content for the first time. Doesn't include the initial paint from *about:blank*. See also [mozbrowserdocumentfirstpaint](#mozbrowserdocumentfirstpaint) and [addNextPaintListener](#addNextPaintListener).
 760 | 
 761 | ## <a name="mozbrowserdocumentfirstpaint">The `mozbrowserdocumentfirstpaint` event</a>
 762 | 
 763 | Sent for every document (across navigation). See also [mozbrowserfindchange](#mozbrowserfindchange) and [addNextPaintListener](#addNextPaintListener).
 764 | 
 765 | ## <a name="mozbrowserclose">The `mozbrowserclose` event</a>
 766 | 
 767 | Window is now closed. Embedder wants to destroy the iframe.
 768 | 
 769 | ## <a name="mozbrowsercontextmenu">The `mozbrowsercontextmenu` event</a>
 770 | 
 771 | User right clicked or long-pressed on page. The event can hold several menu descriptions. For example, if the user clicked on an image nested in a `<a>` tag, 2 menus are available. One with information related to the image, one for the link. The page can also describe its own menus with the <menu> tag.
 772 | 
 773 | ``` javascript
 774 |   event.details = {
 775 | 
 776 |     clientX: Number, // Click coordinates
 777 |     clientY: Number,
 778 | 
 779 |     // Regular menu. One per possible target
 780 |     systemTargets: Array(MenuSystem),
 781 | 
 782 |     // if dom node has a `contextmenu` attribute pointing to a menu element
 783 |     // https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/contextmenu
 784 | 
 785 |     contextmenu: Menu
 786 |     contextMenuItemSelected: function(id)
 787 | 
 788 |   }
 789 | 
 790 |   MenuSystem = {
 791 | 
 792 |     documentURI: String,
 793 | 
 794 |     // link:
 795 |     uri: String, // href
 796 |     text: String, // textContent
 797 | 
 798 |     // image:
 799 |     uri: String, // src
 800 | 
 801 |     // video:
 802 |     url: String, // src
 803 |     hasVideo: Boolean, // true if video has metadata and is bigger than 0x0
 804 | 
 805 |     // input in a <form>:
 806 |     action: String, // from form
 807 |     method: String, // from form
 808 |     name: String // from input
 809 | 
 810 |   }
 811 | 
 812 |   Menu: {
 813 | 
 814 |     type: "menu" | "menuitem",
 815 |     label: String // label attribute from the dom node
 816 | 
 817 |     // if menuitem
 818 |     icon: String,
 819 |     id: String, // used with contextMenuItemSelected()
 820 | 
 821 |     // if menu
 822 |     items: Array(Menu)
 823 | 
 824 |   }
 825 | ```
 826 | 
 827 | ## <a name="mozbrowsererror">The `mozbrowsererror` event</a>
 828 | 
 829 | The page has encountered an error while loading, or crashed.
 830 | 
 831 | ``` javascript
 832 |   event.details = {
 833 |     type: String
 834 |   }
 835 | ```
 836 | 
 837 | Possible errors:
 838 | 
 839 | - `"fatal"` (crash)
 840 | - `"unknownProtocolFound"`
 841 | - `"fileNotFound"`
 842 | - `"dnsNotFound"`
 843 | - `"connectionFailure"`
 844 | - `"netInterrupt"`
 845 | - `"netTimeout"`
 846 | - `"cspBlocked"`
 847 | - `"phishingBlocked"`
 848 | - `"malwareBlocked"`
 849 | - `"unwantedBlocked"`
 850 | - `"offline"`
 851 | - `"malformedURI"`
 852 | - `"redirectLoop"`
 853 | - `"unknownSocketType"`
 854 | - `"netReset"`
 855 | - `"notCached"`
 856 | - `"isprinting"`
 857 | - `"deniedPortAccess"`
 858 | - `"proxyResolveFailure"`
 859 | - `"proxyConnectFailure"`
 860 | - `"contentEncodingFailure"`
 861 | - `"remoteXUL"`
 862 | - `"unsafeContentType"`
 863 | - `"corruptedContentError"`
 864 | - `"certerror"`
 865 | - `"other"`
 866 | 
 867 | ## <a name="mozbrowsersecuritychange">The `mozbrowsersecuritychange` event</a>
 868 | 
 869 | Sent when the SSL and mixed content states change
 870 | 
 871 | ``` javascript
 872 |   event.details = {
 873 | 
 874 |     // "insecure" indicates that the data corresponding to
 875 |     //   the request was received over an insecure channel.
 876 |     //
 877 |     // "broken" indicates an unknown security state.  This
 878 |     //   may mean that the request is being loaded as part
 879 |     //   of a page in which some content was received over
 880 |     //   an insecure channel.
 881 |     //
 882 |     // "secure" indicates that the data corresponding to the
 883 |     //   request was received over a secure channel.
 884 | 
 885 |     state: "insecure" | "broken" | "secure",
 886 | 
 887 |     // "loaded_tracking_content": tracking content has been loaded.
 888 |     // "blocked_tracking_content": tracking content has been blocked from loading.
 889 | 
 890 |     trackingState: "loaded_tracking_content" | "blocked_tracking_content",
 891 | 
 892 |     // "blocked_mixed_active_content": Mixed active content has been blocked from loading.
 893 |     // "loaded_mixed_active_content": Mixed active content has been loaded.
 894 |     mixedState: "blocked_mixed_active_content" | "loaded_mixed_active_content",
 895 |     extendedValidation: Boolean,
 896 |     trackingContent: Boolean,
 897 |     mixedContent: Boolean,
 898 |   }
 899 | ```
 900 | 
 901 | ## <a name="mozbrowserlocationchange">The `mozbrowserlocationchange` event</a>
 902 | 
 903 | Sent when the location change. Happens every time navigation occurs. It's usually the right time to call [getCanGoBack](#getCanGoBack) and [getCanGoForward](#getCanGoForward).
 904 | 
 905 | ``` javascript
 906 |   event.details = String; // new url
 907 | ```
 908 | 
 909 | ## <a name="mozbrowsericonchange">The `mozbrowsericonchange` event</a>
 910 | 
 911 | Sent when a new icon (`<link rel=icon|apple-touch-icon>`) is available
 912 | 
 913 | ``` javascript
 914 |   event.details = {
 915 |     href: url,
 916 |     sizes: String, // optional. "16x16" or "16x16 32x32" or "any"
 917 |     rel: String, // optional. "apple-touch-icon" "shortcut icon", "icon"
 918 |   }
 919 | ```
 920 | 
 921 | ## <a name="mozbrowserscrollareachanged">The `mozbrowserscrollareachanged` event</a>
 922 | 
 923 | Sent when the available scrolling area changes. Happens on resize and when the page size changes (while loading for example).
 924 | 
 925 | ``` javascript
 926 |   event.details =  {
 927 |     width: Number,
 928 |     height: Number,
 929 |   }
 930 | ```
 931 | 
 932 | ## <a name="mozbrowseropensearch">The `mozbrowseropensearch` event</a>
 933 | 
 934 | Sent when page encounter `<link rel=search type=application/opensearchdescription+xml>`.
 935 | 
 936 | ``` javascript
 937 |   event.details = {
 938 |     title,
 939 |     href
 940 |   }
 941 | ```
 942 | 
 943 | ## <a name="mozbrowsermanifestchange">The `mozbrowsermanifestchange` event</a>
 944 | 
 945 | Sent when the manifest url changes `<link rel=manifest href=…>`.
 946 | 
 947 | ``` 
 948 |   event.details = {
 949 |     href: String,
 950 |   }
 951 | ```
 952 | 
 953 | ## <a name="mozbrowsermetachange">The `mozbrowsermetachange` event</a>
 954 | 
 955 | Sent when a `<meta>` tag is added, removed or changed.
 956 | 
 957 | ``` javascript
 958 |   event.details = {
 959 |     name: 'viewmode' | 'theme-color' | 'theme-group' | 'application-name',
 960 |     content: String // <meta content=…>
 961 |     type: 'added' | 'changed' | 'removed', // optional
 962 |     lang: String, // optional
 963 |   }
 964 | ```
 965 | 
 966 | ## <a name="mozbrowserresize">The `mozbrowserresize` event</a>
 967 | 
 968 | Window size has changed.
 969 | 
 970 | ``` javascript
 971 |   event.details = {
 972 |     width: Number,
 973 |     height: Number,
 974 |   }
 975 | ```
 976 | 
 977 | ## <a name="mozbrowseractivitydone">The `mozbrowseractivitydone` event</a>
 978 | 
 979 | FIXME
 980 | 
 981 | ``` javascript
 982 |   event.details = {
 983 |     success: Boolean
 984 |   }
 985 | ```
 986 | 
 987 | ## <a name="mozbrowserscroll">The `mozbrowserscroll` event</a>
 988 | 
 989 | Content has scrolled.
 990 | 
 991 | ``` javascript
 992 |   event.details = {
 993 |     top: Number,
 994 |     left: Number,
 995 |   }
 996 | ```
 997 | 
 998 | ## <a name="mozbrowserasyncscroll">The `mozbrowserasyncscroll` event</a>
 999 | 
1000 | Content has scrolled (apzc version).
1001 | 
1002 | ``` javascript
1003 |   event.details = {
1004 |     left: Number,
1005 |     top: Number,
1006 |     width: Number,
1007 |     height: Number,
1008 |     scrollWidth: Number,
1009 |     scrollHeight: Number,
1010 |   }
1011 | ```
1012 | 
1013 | ## <a name="mozbrowseropentab">The `mozbrowseropentab` event</a>
1014 | 
1015 | User *middle|ctrl|cmd* clicked on a link
1016 | 
1017 | ``` javascript
1018 |   event.details = {
1019 |     url: String,
1020 |   }
1021 | ```
1022 | 
1023 | ## <a name="mozbrowseropenwindow">The `mozbrowseropenwindow` event</a>
1024 | 
1025 | A new window is required. Usually happens when the user clicked on link with a unknown target. The embedder must use the passed `frameElement` DOM node.
1026 | 
1027 | ``` javascript
1028 |   event.details = {
1029 |     url: String,
1030 |     name: String,
1031 | 
1032 |     // See https://developer.mozilla.org/en-US/docs/Web/API/Window/open
1033 |     features: String,
1034 | 
1035 |     // The event provides an iframe.
1036 |     // For a window sharing the same domain of its parent for example,
1037 |     // it will use the same process
1038 | 
1039 |     frameElement: HTMLIFrameElement
1040 |   }
1041 | ```
1042 | 
1043 | ## <a name="mozbrowseraudioplaybackchange">The `mozbrowseraudioplaybackchange` event</a>
1044 | 
1045 | Sent when audio starts or stops playing
1046 | 
1047 | ``` javascript
1048 |   event.details = Boolean; // playing or not
1049 | ```
1050 | 
1051 | ## <a name="mozbrowserusernameandpasswordrequired">The `mozbrowserusernameandpasswordrequired` event</a>
1052 | 
1053 | Authentification required. The embedder is supposed retrieve credentials, usually via a dialog or a database of username/passwords, and then call `authenticate()` or `cancel()`.
1054 | 
1055 | ``` javascript
1056 |   event.details = {
1057 |     host: String,
1058 |     realm: String,
1059 |     isProxy: Boolean,
1060 | 
1061 |     // Embedder should call once of these functions
1062 |     authenticate: function("user", "password"),
1063 |     cancel: function(),
1064 |   }
1065 | ```
1066 | 
1067 | ## <a name="mozbrowsershowmodalprompt">The `mozbrowsershowmodalprompt` event</a>
1068 | 
1069 | Embedder should show a dialog.
1070 | 
1071 | ``` javascript
1072 |   event.details = {
1073 | 
1074 |     promptType: "alert" | "confirm"
1075 |     title: String,
1076 |     message: String,
1077 | 
1078 |     // Embedder should set returnValue
1079 |     returnValue: undefined,
1080 | 
1081 |     // If the embedder calls preventDefault() on this event,
1082 |     // the iframe is blocked until unblock() is called.
1083 |     unblock: function(),
1084 | 
1085 |   }
1086 | 
1087 |   // or:
1088 | 
1089 |   event.details = {
1090 | 
1091 |     promptType: "custom-prompt",
1092 |     // FIXME More things! See BrowserElementPromptService.jsm:confirmEx implementation
1093 | 
1094 |   }
1095 | ```
1096 | 
1097 | ## <a name="mozbrowserselectionstatechanged">The `mozbrowserselectionstatechanged` event</a>
1098 | 
1099 | Selection changed.
1100 | 
1101 | **Deprecated**. See [mozbrowsercaretstatechanged](#mozbrowsercaretstatechanged).
1102 | 
1103 | ``` javascript
1104 |   event.details = {
1105 | 
1106 |     rect: {
1107 |       // Contains bounding rectangle of selection
1108 |       width: Number,
1109 |       height: Number,
1110 |       top: Number,
1111 |       bottom: Number,
1112 |       left: Number,
1113 |       right: Number,
1114 |     },
1115 | 
1116 |     commands: {
1117 |       // Describe what commands can be executed in child. Include canSelectAll,
1118 |       // canCut, canCopy and canPaste. For example: if we want to check if cut
1119 |       // command is available, using following code, if (event.commands.canCut) {}.
1120 |       canSelectAll: Boolean,
1121 |       canCut: Boolean,
1122 |       canCopy: Boolean,
1123 |       canPaste: Boolean
1124 |     },
1125 | 
1126 |     zoomFactor: Number, // Current zoom factor in child frame.
1127 |     isCollapsed: Boolean, // Indicate current selection is collapsed or not.
1128 |     visible: Boolean, // Indicate selection visibility
1129 |     states: FIXME,
1130 |   }
1131 | ```
1132 | 
1133 | ## <a name="mozbrowsercaretstatechanged">The `mozbrowsercaretstatechanged` event</a>
1134 | 
1135 | Sent when the user select content in the page. Used by the embedder to show a context menu for clipboard actions.
1136 | 
1137 | ``` javascript
1138 |   event.details = {
1139 | 
1140 |     rect: {
1141 |       // Contains bounding rectangle of selection
1142 |       width: Number,
1143 |       height: Number,
1144 |       top: Number,
1145 |       bottom: Number,
1146 |       left: Number,
1147 |       right: Number,
1148 |     },
1149 | 
1150 |     commands: {
1151 |       // Describe what commands can be executed in child.
1152 |       // For example: if we want to check if cut command is available, using following code,
1153 |       // if (event.details.commands.canCut) {event.details.sendDoCommandMsg('cut')}.
1154 |       canSelectAll: Boolean,
1155 |       canCut: Boolean,
1156 |       canCopy: Boolean,
1157 |       canPaste: Boolean
1158 |     },
1159 | 
1160 |     // The reason causes the state changed. Include "visibilitychange",
1161 |     // "updateposition", "longpressonemptycontent", "taponcaret", "presscaret",
1162 |     // "releasecaret".
1163 |     reason: String,
1164 | 
1165 |     zoomFactor: Number, // Current zoom factor in child frame.
1166 |     collapsed: Boolean, // Indicate current selection is collapsed or not.
1167 |     caretVisible: Boolean, // Indicate the caret visiibility.
1168 |     selectionVisible: Boolean, // Indicate current selection is visible or not.
1169 |     selectionEditable: Boolean, // Indicate current selection is editable or not.
1170 |     selectedTextContent: String, // Contains current selected text content.
1171 | 
1172 |     // Possible commands: cut, copy, paste, selectall
1173 |     sendDoCommandMsg: function(command),
1174 | 
1175 |   }
1176 | ```
1177 | 
1178 | ## <a name="mozbrowserscrollviewchange">The `mozbrowserscrollviewchange` event</a>
1179 | 
1180 | Sent when async scroll starts and stops.
1181 | 
1182 | FIXME: I think this only happens if caret is enabled
1183 | 
1184 | ``` javascript
1185 |   event.details = {
1186 |     state: "started" | "stopped"
1187 |   }
1188 | ```
1189 | 
1190 | ## <a name="mozbrowserfindchange">The `mozbrowserfindchange` event</a>
1191 | 
1192 | Sent after [findAll](#findAll), [findNext](#findNext) and [clearMatch](#clearMatch) are called.
1193 | 
1194 | ``` javascript
1195 |   event.details = {
1196 | 
1197 |     // Search is active.
1198 |     active: true,
1199 | 
1200 |     // The current searched string
1201 |     searchString: String
1202 | 
1203 |     // Number of maximum possible results (0 -> no limit)
1204 |     searchLimit: Number,
1205 | 
1206 |     // Highlighted result position
1207 |     activeMatchOrdinal: Number,
1208 | 
1209 |     // Number of result
1210 |     numberOfMatches: Number,
1211 |   }
1212 | 
1213 |   // or
1214 | 
1215 |   event.details = {
1216 |     // Search is not active.
1217 |     active: false
1218 |   }
1219 | ```
1220 | 


--------------------------------------------------------------------------------