browser API events

events.js

// Sent when the browser <iframe> starts to load a new page.
// This is usually when the embedder wants to start spinning
// a loading indicator.
"loadstart";

// 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.
"loadend";

  event.details = {
    backgroundColor: String
  }

// Sent when the top level window title changed
"titlechange";

  event.details = String;


// Sent when the visibility state of the iframe changed.
// See also iframe.setVisible().
"visibilitychange";

  event.details = {
    visible: Boolean
  }


// Sent when the iframe paints content for the first time.
// Doesn't include the initial paint from about:blank.
"firstpaint";

// Sent for every document (across navigation).
"documentfirstpaint";

// Window is now closed. Embedder wants to destroy the iframe.
"close";

// 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.
"contextmenu";

  event.details = {
    clientX: Number, // Click coordinates
    clientY: Number,

    // Regular menu. One per possible target
    systemTargets: Array(MenuSystem),

    // if dom node has a `contextmenu` attribute pointing to a menu element
    // https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/contextmenu
    contextmenu: Menu
    contextMenuItemSelected: function(id)
  }

  MenuSystem = {
    documentURI: String,
    
    // link:
    uri: String, // href
    text: String, // textContent
    
    // image:
    uri: String, // src
    
    // video:
    url: String, // src
    hasVideo: Boolean, // true if video has metadata and is bigger than 0x0
    
    // input in a <form>:
    action: String, // from form
    method: String, // from form
    name: String // from input
  }

  Menu: {
    type: "menu" | "menuitem",
    label: String // label attribute from the dom node
    // if menuitem
    icon: String,
    id: String, // used with contextMenuItemSelected()
    // if menu
    items: Array(Menu)
  }

// The page has encountered an error while loading, or crashed.
"error";

  event.details = {
    // Possible errors:`fatal` (crash) `unknownProtocolFound`
    // `fileNotFound` `dnsNotFound` `connectionFailure` `netInterrupt`
    // `netTimeout` `cspBlocked` `phishingBlocked` `malwareBlocked`
    // `unwantedBlocked` `offline` `malformedURI` `redirectLoop`
    // `unknownSocketType` `netReset` `notCached` `isprinting`
    // `deniedPortAccess` `proxyResolveFailure` `proxyConnectFailure`
    // `contentEncodingFailure` `remoteXUL` `unsafeContentType`
    // `corruptedContentError` `certerror` `other`
    type: String
  }


// Sent when the SSL and mixed content states change
"securitychange";

  event.details = {
    // "insecure" indicates that the data corresponding to
    //   the request was received over an insecure channel.
    //
    // "broken" indicates an unknown security state.  This
    //   may mean that the request is being loaded as part
    //   of a page in which some content was received over
    //   an insecure channel.
    //
    // "secure" indicates that the data corresponding to the
    //   request was received over a secure channel.
    state: "insecure" | "broken" | "secure",
    

    // "loaded_tracking_content": tracking content has been loaded.
    // "blocked_tracking_content": tracking content has been blocked from loading.
    trackingState: "loaded_tracking_content" | "blocked_tracking_content",


    // "blocked_mixed_active_content": Mixed active content has been blocked from loading.
    // "loaded_mixed_active_content": Mixed active content has been loaded.
    mixedState: "blocked_mixed_active_content" | "loaded_mixed_active_content",

    extendedValidation: Boolean,
    trackingContent: Boolean,
    mixedContent: Boolean,

  }

// Sent when the location change. Happens everytime navigation occurs.
// It's usually the right time to call getCanGoBack/getCanGoForward
"locationchange";

  event.details = String; // new url

// Sent when a new icon (<link rel=icon|apple-touch-icon>) is available
"iconchange";

  event.details = {
    href: url,
    sizes: String, // optional. "16x16" or "16x16 32x32" or "any"
    rel: String, // optional. "apple-touch-icon" "shortcut icon", "icon"
  }


// Sent when the available scrolling area changes. Should happen on resize
// and when the page size changes (at loading for example).
"scrollareachanged";

  event.details =  {
    width: Number,
    height: Number,
  }

// Sent when page encounter <link rel=search type=application/opensearchdescription+xml>
"opensearch";

  event.details = {
    title,
    href
  }

// Sent when the manfiest url changes <link rel=manifest href=…>
"manifestchange";

  event.details = {
    href: String,
  }

// Sent when a <meta> tag is added, removed or changed
"metachange";
  
  event.details = {
    name: 'viewmode' | 'theme-color' | 'theme-group' | 'application-name',
    content: String // <meta content=…>
    type: 'added' | 'changed' | 'removed', // optional
    lang: String, // optional
  }

// Window size has changed
"resize";

  event.details = {
    width: Number,
    height: Number,
  }

// FIXME
"activitydone";

  event.details = {
    success: Boolean
  }

// Content has scrolled
"scroll";

  event.details = {
    top: Number,
    left: Number,
  }

// Content has scrolled (apzc version)
"asyncscroll";

  event.details = {
    left: Number,
    top: Number,
    width: Number,
    height: Number,
    scrollWidth: Number,
    scrollHeight: Number,
  }

// User middle|ctrl|cmd clicked on a link
"opentab";

  event.details = {
    url: String,
  }

// A new window is required. Usually happens when the user clicked on
// link with a unknown target
"openwindow";

  event.details = {
    url: String,
    name: String,
    // See https://developer.mozilla.org/en-US/docs/Web/API/Window/open
    features: String,
    // The event provides an iframe.
    // For a window sharing the same domain of its parent for exeample,
    // it will use the same process
    frameElement: HTMLIFrameElement
  }

// Sent when audio starts or stops playing
"audioplaybackchange";

  event.details = Boolean; // playing or not

// Authentification required. The embedder is supposed retrieve
// credentials, usually via a dialog or a database of username/passwords.
"usernameandpasswordrequired";

  event.details = {
    host: String,
    realm: String,
    isProxy: Boolean,
    // Embedder should call once of these functions
    authenticate: function("user", "password"),
    cancel: function(),
  }

// Embedder should show a dialog
"showmodalprompt";

  event.details = {
    promptType: "alert" | "confirm"
    title: String,
    message: String,
    // Embedder should set returnValue
    returnValue: undefined,
    // If the embedder calls preventDefault() on this event,
    // the iframe is blocked until unblock() is called.
    unblock: function(),
  }

  // or:

  event.details = {
    promptType: "custom-prompt",
    // FIXME More things! See BrowserElementPromptService.jsm:confirmEx implementation
  }

// Selection changed
"selectionstatechanged"; // FIXME: I think this is deprecated

  event.details = {
    rect: {
      // Contains bounding rectangle of selection
      width: Number,
      height: Number,
      top: Number,
      bottom: Number,
      left: Number,
      right: Number,
    },

    commands: {
      // Describe what commands can be executed in child. Include canSelectAll,
      // canCut, canCopy and canPaste. For example: if we want to check if cut
      // command is available, using following code, if (event.commands.canCut) {}.
      canSelectAll: Boolean,
      canCut: Boolean,
      canCopy: Boolean,
      canPaste: Boolean
    },

    zoomFactor: Number, // Current zoom factor in child frame.
    isCollapsed: Boolean, // Indicate current selection is collapsed or not.
    visible: Boolean, // Indicate selection visibility
    states: FIXME,
  }

// Sent when the user select content in the page
"caretstatechanged";

  event.details = {
    rect: {
      // Contains bounding rectangle of selection
      width: Number,
      height: Number,
      top: Number,
      bottom: Number,
      left: Number,
      right: Number,
    },

    commands: {
      // Describe what commands can be executed in child. Include canSelectAll,
      // canCut, canCopy and canPaste. For example: if we want to check if cut
      // command is available, using following code, if (event.commands.canCut) {}.
      canSelectAll: Boolean,
      canCut: Boolean,
      canCopy: Boolean,
      canPaste: Boolean
    },

    // The reason causes the state changed. Include "visibilitychange",
    // "updateposition", "longpressonemptycontent", "taponcaret", "presscaret",
    // "releasecaret".
    reason: String,
    zoomFactor: Number, // Current zoom factor in child frame.
    collapsed: Boolean, // Indicate current selection is collapsed or not.
    caretVisible: Boolean, // Indicate the caret visiibility.
    selectionVisible: Boolean, // Indicate current selection is visible or not.
    selectionEditable: Boolean, // Indicate current selection is editable or not.

    // Possible commands: cmd_cut, cmd_copy, cmd_paste, cmd_selectAll
    sendDoCommandMsg: function(command),
  }


// Sent when async scroll starts and stops.
// FIXME: I think this only happens if caret is enabled
"scrollviewchange";

  event.details = {
    state: "started" | "stopped"
  }

// Sent after findAll and findNext are called.
"findchange";

  event.details = {
    active: true,
    searchString: String
    searchLimit: Number,
    activeMatchOrdinal: Number,
    numberOfMatches: Number,
  }

  // or

  event.details = {
    active: false
  }