The Tor Browser: comparison browser/modules/SharedFrame.jsm

--1:000000000000
+:76d197d1b662
+/* This Source Code Form is subject to the terms of the Mozilla Public
+* License, v. 2.0. If a copy of the MPL was not distributed with this
+* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+"use strict";
+this.EXPORTED_SYMBOLS = [ "SharedFrame" ];
+const Ci = Components.interfaces;
+const Cu = Components.utils;
+/**
+* The purpose of this module is to create and group various iframe
+* elements that are meant to all display the same content and only
+* one at a time. This makes it possible to have the content loaded
+* only once, while the other iframes can be kept as placeholders to
+* quickly move the content to them through the swapFrameLoaders function
+* when another one of the placeholder is meant to be displayed.
+* */
+let Frames = new Map();
+/**
+* The Frames map is the main data structure that holds information
+* about the groups being tracked. Each entry's key is the group name,
+* and the object holds information about what is the URL being displayed
+* on that group, and what is the active element on the group (the frame that
+* holds the loaded content).
+* The reference to the activeFrame is a weak reference, which allows the
+* frame to go away at any time, and when that happens the module considers that
+* there are no active elements in that group. The group can be reactivated
+* by changing the URL, calling preload again or adding a new element.
+*
+*
+*  Frames = {
+*    "messages-panel": {
+*      url: string,
+*      activeFrame: weakref
+*    }
+*  }
+*
+* Each object on the map is called a _SharedFrameGroup, which is an internal
+* class of this module which does not automatically keep track of its state. This
+* object should not be used externally, and all control should be handled by the
+* module's functions.
+*/
+function UNLOADED_URL(aStr) "data:text/html;charset=utf-8,<!-- Unloaded frame " + aStr + " -->";
+this.SharedFrame = {
+/**
+* Creates an iframe element and track it as part of the specified group
+* The module must create the iframe itself because it needs to do some special
+* handling for the element's src attribute.
+*
+* @param aGroupName        the name of the group to which this frame belongs
+* @param aParent           the parent element to which the frame will be appended to
+* @param aFrameAttributes  an object with a list of attributes to set in the iframe
+*                          before appending it to the DOM. The "src" attribute has
+*                          special meaning here and if it's not blank it specifies
+*                          the URL that will be initially assigned to this group
+* @param aPreload          optional, tells if the URL specified in the src attribute
+*                          should be preloaded in the frame being created, in case
+*                          it's not yet preloaded in any other frame of the group.
+*                          This parameter has no meaning if src is blank.
+*/
+createFrame: function (aGroupName, aParent, aFrameAttributes, aPreload = true) {
+let frame = aParent.ownerDocument.createElement("iframe");
+for (let [key, val] of Iterator(aFrameAttributes)) {
+frame.setAttribute(key, val);
+}
+let src = aFrameAttributes.src;
+if (!src) {
+aPreload = false;
+}
+let group = Frames.get(aGroupName);
+if (group) {
+// If this group has already been created
+if (aPreload && !group.isAlive) {
+// If aPreload is set and the group is not already loaded, load it.
+// This can happen if:
+// - aPreload was not used while creating the previous frames of this group, or
+// - the previously active frame went dead in the meantime
+group.url = src;
+this.preload(aGroupName, frame);
+} else {
+// If aPreload is not set, or the group is already loaded in a different frame,
+// there's not much that we need to do here: just create this frame as an
+// inactivate placeholder
+frame.setAttribute("src", UNLOADED_URL(aGroupName));
+}
+} else {
+// This is the first time we hear about this group, so let's start tracking it,
+// and also preload it if the src attribute was set and aPreload = true
+group = new _SharedFrameGroup(src);
+Frames.set(aGroupName, group);
+if (aPreload) {
+this.preload(aGroupName, frame);
+} else {
+frame.setAttribute("src", UNLOADED_URL(aGroupName));
+}
+}
+aParent.appendChild(frame);
+return frame;
+},
+/**
+* Function that moves the loaded content from one active frame to
+* another one that is currently a placeholder. If there's no active
+* frame in the group, the content is loaded/reloaded.
+*
+* @param aGroupName   the name of the group
+* @param aTargetFrame the frame element to which the content should
+*                     be moved to.
+*/
+setOwner: function (aGroupName, aTargetFrame) {
+let group = Frames.get(aGroupName);
+let frame = group.activeFrame;
+if (frame == aTargetFrame) {
+// nothing to do here
+return;
+}
+if (group.isAlive) {
+// Move document ownership to the desired frame, and make it the active one
+frame.QueryInterface(Ci.nsIFrameLoaderOwner).swapFrameLoaders(aTargetFrame);
+group.activeFrame = aTargetFrame;
+} else {
+// Previous owner was dead, reload the document at the new owner and make it the active one
+aTargetFrame.setAttribute("src", group.url);
+group.activeFrame = aTargetFrame;
+}
+},
+/**
+* Updates the current URL in use by this group, and loads it into the active frame.
+*
+* @param aGroupName  the name of the group
+* @param aURL        the new url
+*/
+updateURL: function (aGroupName, aURL) {
+let group = Frames.get(aGroupName);
+group.url = aURL;
+if (group.isAlive) {
+group.activeFrame.setAttribute("src", aURL);
+}
+},
+/**
+* Loads the group's url into a target frame, if the group doesn't have a currently
+* active frame.
+*
+* @param aGroupName    the name of the group
+* @param aTargetFrame  the frame element which should be made active and
+*                      have the group's content loaded to
+*/
+preload: function (aGroupName, aTargetFrame) {
+let group = Frames.get(aGroupName);
+if (!group.isAlive) {
+aTargetFrame.setAttribute("src", group.url);
+group.activeFrame = aTargetFrame;
+}
+},
+/**
+* Tells if a group currently have an active element.
+*
+* @param aGroupName  the name of the group
+*/
+isGroupAlive: function (aGroupName) {
+return Frames.get(aGroupName).isAlive;
+},
+/**
+* Forgets about this group. This function doesn't need to be used
+* unless the group's name needs to be reused.
+*
+* @param aGroupName  the name of the group
+*/
+forgetGroup: function (aGroupName) {
+Frames.delete(aGroupName);
+}
+}
+function _SharedFrameGroup(aURL) {
+this.url = aURL;
+this._activeFrame = null;
+}
+_SharedFrameGroup.prototype = {
+get isAlive() {
+let frame = this.activeFrame;
+return !!(frame &&
+frame.contentDocument &&
+frame.contentDocument.location);
+},
+get activeFrame() {
+return this._activeFrame &&
+this._activeFrame.get();
+},
+set activeFrame(aActiveFrame) {
+this._activeFrame = aActiveFrame
+? Cu.getWeakReference(aActiveFrame)
+: null;
+}
+}

The Tor Browser / file comparison

comparison: browser/modules/SharedFrame.jsm

browser/modules/SharedFrame.jsm