Travailler avec des fenêtres dans le chrome

Cet article décrit la manière de travailler avec des fenêtres multiples dans le code chrome de Mozilla (applications XUL et extensions). Il donne des astuces et des exemples de code sur l'ouverture de nouvelles fenêtres, la recherche de fenêtres déjà ouvertes, et la transmission de données entre différentes fenêtres.

Ouverture de fenêtres

Pour ouvrir une nouvelle fenêtre, on utilise habituellement un appel DOM window.open ou window.openDialog, comme ceci :

var win = window.open("chrome://myextension/content/about.xul", 
                      "aproposDeMonExtension", "chrome,centerscreen"); 

Le premier paramètre de window.open est l'URI du fichier XUL décrivant la fenêtre et son contenu.

Le second paramètre est le nom de la fenêtre ; il peut être utilisé par des liens ou formulaires dans leur attribut target. Il est différent du titre de la fenêtre tel que vu par l'utilisateur, qui est spécifié en XUL.

Le troisième paramètre, facultatif, est une liste de fonctionnalités spéciales que la fenêtre doit avoir.

La fonction window.openDialog fonctionne de manière similaire, mais permet de spécifier des paramètres optionnels qui peuvent être référencés depuis le code JavaScript. Elle gère également les fonctionnalités de la fenêtre légèrement différemment, supposant notamment toujours que la fonctionnalité dialog est spécifiée.

Si l'objet window est indisponible (par exemple, lors de l'ouverture d'une fenêtre depuis le code d'un composant XPCOM), vous pouvez avoir besoin de l'interface nsIWindowWatcher. Ses paramètres sont similaires à ceux de window.open, en fait l'implémentation de window.open appelle les méthodes de nsIWindowWatcher.

var ww = Components.classes["@mozilla.org/embedcomp/window-watcher;1"]
                   .getService(Components.interfaces.nsIWindowWatcher);
var win = ww.openWindow(null, "chrome://myextension/content/about.xul",
                        "aboutMyExtension", "chrome,centerscreen", null);

L'objet window

Notez la variable win dans la section ci-dessus, à laquelle est assignée la valeur de retour de window.open. Elle peut être utilisée pour accéder à la fenêtre ouverte. La valeur renvoyée par window.open (et les méthodes similaires) est un objet Window (habituellement ChromeWindow), du même type que la variable window.

Du point de vue technique, elle implémente un certain nombre d'interfaces, dont nsIDOMJSWindow et nsIDOMWindowInternal, mais elle contient également les propriétés définies par l'utilisateur pour les variables globales et fonctions de la fenêtre. Donc, par exemple, pour accéder au document DOM correspondant à la fenêtre, vous pouvez utiliser win.document.

Notez cependant que le retour de l'appel à open() se fait avant que la fenêtre ne soit totalement chargée, donc certains appels comme win.document.getElementById() ne fonctionneront pas. Pour contourner cette difficulté, vous pouvez déplacer le code d'initialisation vers un gestionnaire load de la fenêtre ouverte, ou passer une fonction de callback comme décrit ci-dessous.

Vous pouvez obtenir un objet Window depuis un document à l'aide de document.defaultView.

Fenêtres de contenu

Lorsqu'une fenêtre XUL contient un élément d'interface capable d'afficher une page, comme <browser> ou <iframe>, le document à l'intérieur de celui-ci est, naturellement, séparé du document de la fenêtre chrome elle-même. Il y a également un objet Window pour chaque sous-document, bien qu'il n'y ait pas de fenêtre dans le sens commun pour le sous-document.

C'est également valable pour les fenêtres chrome ouvertes dans un onglet ou <tt><tabbrowser></tt>. Les éléments au dessus du document chrome ouvert dans l'onglet sont séparés de votre document chrome.

Les deux sous-sections qui suivent décrivent la manière de passer les frontières du contenu chrome dans les deux sens, c'est-à-dire d'accéder à des éléments qui sont les ancêtres de votre document chrome, ou des éléments qui sont descendants de votre document chrome, mais néanmoins dans un contexte différent.

Accès aux documents contenus

Supposons que vous avez un document chargé dans un élément <tt><tabbrowser></tt>, <tt><browser></tt> ou <tt><iframe></tt> dans votre document. Vous pouvez utiliser browser.contentDocument pour accéder à ce document et browser.contentWindow pour accéder à l'objet Window de ce document.

Il est nécessaire de prendre en compte la fonctionnalité XPCNativeWrapper si l'on n'opère pas dans du contenu de confiance.

Dans le cas de <browser type="content-primary"/>, vous pouvez utiliser la propriété raccourcie content pour accéder à l'objet Window du document contenu. Par exemple :

// affiche le titre du document affiché dans l'élément de contenu principal
alert(content.document.title);

Par exemple, vous pouvez utiliser content.document dans un overlay à browser.xul pour accéder à la page Web dans l'onglet sélectionné.

Accès à un document dans un panneau latéral

Firefox permet d'accéder à un panneau latéral, qui est implémenté comme un élément <browser> avec id="sidebar". Pour accéder aux éléments et variables à l'intérieur du panneau, il est nécessaire d'utilier document.getElementById("sidebar").contentDocument ou .contentWindow, comme pour l'Accès aux documents contenus.

Accès aux éléments du document de la fenêtre principale depuis une fenêtre fille

Le cas opposé est l'accès au document chrome depuis un script privilégié chargé dans un <tt><browser></tt> ou un <tt><iframe></tt>.

Un cas typique où cela peut s'avérer utile est lorsque du code exécuté dans un panneau latéral de la fenêtre principale de Firefox doit pouvoir accéder aux éléments de cette fenêtre.

L'arbre DOM, tel qu'il apparaît dans l'Inspecteur DOM, peut ressembler à ceci :

#document
  window                 main-window
    ...
      browser
        #document
          window         myExtensionWindow

où la fenêtre fille est celle où se trouve votre code.

Le but est d'accéder aux éléments situés au dessus du document chrome, c'est-à-dire de sortir de la fenêtre chrome et d'accéder à ses ancêtres. Cela peut se faire à l'aide de l'instruction suivante :

var mainWindow = window.QueryInterface(Components.interfaces.nsIInterfaceRequestor)
                   .getInterface(Components.interfaces.nsIWebNavigation)
                   .QueryInterface(Components.interfaces.nsIDocShellTreeItem)
                   .rootTreeItem
                   .QueryInterface(Components.interfaces.nsIInterfaceRequestor)
                   .getInterface(Components.interfaces.nsIDOMWindow) 

Ceci permet de passer les limites du contenu chrome, et renvoie l'objet de la fenêtre principale.

Recherche de fenêtres déjà ouvertes

Le composant XPCOM window mediator (interface nsIWindowMediator) fournit des informations à propos des fenêtres existantes. Deux de ses méthodes sont souvent utilisées pour obtenir des informations à propos des fenêtres actuellement ouvertes : getMostRecentWindow et getEnumerator. Consultez la page nsIWindowMediator pour plus d'informations sur nsIWindowMediator. === Example: Opening a window only if it's not opened already === XXX TBD

Transfert de données entre fenêtres

Lorsque l'on travaille avec plusieurs fenêtres, il est souvent nécessaire de faire passer des informations d'une fenêtre à une autre. Comme des fenêtres séparées ont des documents DOM et objets globaux différents pour les scripts, il n'est pas possible d'utiliser une seule variable globale JavaScript dans des scripts de fenêtres différentes.

Plusieurs techniques existent, de puissance et de simplicité variables, pour partager des données. Nous les présenterons de la plus simple à la plus complexe dans les quelques sections suivantes.

Exemple 1 : Passage de données à une fenêtre à son ouverture avec openDialog

Lorsque vous ouvrez une fenêtre à l'aide de window.openDialog ou nsIWindowWatcher.openWindow, vous pouvez fournir un nombre d'arguments arbitraires à cette fenêtre. Les arguments sont des objets JavaScript simples, accessibles au travers de la propriété window.arguments dans la fenêtre ouverte.

Dans cet exemple, on utilise window.openDialog pour ouvrir un dialogue de progression. On lui passe le texte d'état ainsi que les valeurs maximale et courante de la barre de progression. (Notez qu'utiliser nsIWindowWatcher.openWindow est un peu moins trivial .)

Code d'ouverture :

window.openDialog("chrome://test/content/progress.xul",
                  "myProgress", "chrome,centerscreen", 
                  {status: "Lecture des données distantes", maxProgress: 50, progress: 10} );

progress.xul:

<?xml version="1.0"?>
<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>

<window onload="onLoad();" xmlns="https://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
<script><![CDATA[
  var gStatus, gProgressMeter;
  var maxProgress = 100;
  function onLoad() {
    gStatus = document.getElementById("status");
    gProgressMeter = document.getElementById("progressmeter");
  
    if("arguments" in window && window.arguments.length > 0) {
      maxProgress = window.arguments[0].maxProgress;
      setProgress(window.arguments[0].progress);
      setStatus(window.arguments[0].status);
    }
  }

  function setProgress(value) {
    gProgressMeter.value = 100 * value / maxProgress;
  }

  function setStatus(text) {
    gStatus.value = "Status: " + text + "...";
  }
]]></script>
 
<label id="status" value="(Aucun état)"/>
<hbox>
  <progressmeter id="progressmeter" mode="determined"/>
  <button label="Annuler" oncommand="close();"/>
</hbox>

</window>

Exemple 2 : Interaction avec la fenêtre ouvrante

Il arrive qu'une fenêtre ouverte doive interagir avec celle qui a déclenché son ouverture (opener). Par exemple, cela peut avoir pour but de lui indiquer que l'utilisateur a effectué des changements dans la fenêtre. On peut trouver la fenêtre qui en a ouvert une autre à l'aide de sa propriété window.opener ou via une fonction de callback passée à la fenêtre, de la façon décrite dans la section précédente.

Ajoutons un peu de code à l'exemple précédent pour avertir la fenêtre ouvrante lorsque l'utilisateur appuie sur Annuler dans la fenêtre de progression.

• Avec window.opener. La propriété opener renvoie l'objet Window pour la fenêtre qui a ouvert la fenêtre courante. Si nous sommes certains que la fenêtre qui a ouvert le dialogue de progression a déclaré la fonction cancelOperation, nous pouvons utiliser window.opener.cancelOperation(); pour lui envoyer une notification :

<button label="Annuler" oncommand="opener.cancelOperation(); close();"/>

• Avec une fonction de callback. Une autre manière de faire est de passer une fonction de callback depuis la fenêtre ouvrante vers le dialogue de progression de la même manière que nous avons passé le message d'état dans l'exemple précédent :

function onCancel() {
  alert("Opération annulée.");
}

...

window.openDialog("chrome://test/content/progress.xul",
                  "myProgress", "chrome,centerscreen", 
                  {status: "Lecture des données distantes", maxProgress: 50, progress: 10},
                  onCancel); 

<button label="Cancel" oncommand="window.arguments[1](); close();"/>

var wm = Components.classes["@mozilla.org/appshell/window-mediator;1"]
                   .getService(Components.interfaces.nsIWindowMediator);
var browserWindow = wm.getMostRecentWindow("navigator:browser");
// lecture de valeurs depuis |browserWindow|

Components.classes["@domain.org/mycomponent;1"].getService();

var prefs = Components.classes["@mozilla.org/preferences-service;1"]
                      .getService(Components.interfaces.nsIPrefService);
var branch = prefs.getBranch("extensions.myext.");
var var1 = branch.getBoolPref("var1"); // obtient une préférence

var hiddenWindow = Components.classes["@mozilla.org/appshell/appShellService;1"]
         .getService(Components.interfaces.nsIAppShellService)
         .hiddenDOMWindow;
hiddenWindow.myExtensionStatus = "ready";

var hiddenWindow = Components.classes["@mozilla.org/appshell/appShellService;1"]
         .getService(Components.interfaces.nsIAppShellService)
         .hiddenDOMWindow;
hiddenWnd.Components.classes["@mozilla.org/moz/jssubscript-loader;1"]
         .getService(Components.interfaces.mozIJSSubScriptLoader)
         .loadSubScript("chrome://my-extension/content/globalObject.js");
hiddenWnd.myExtensionObject.doSomething();

var myExtensionObject = {
  doSomething: function() {
    return new XMLHttpRequest();
  }
}