Janelas

Enumera e examina janelas do navegador abertas, abre novas janelas, e escuta por eventos de janela.

Uso

O módulo windows fornece funções básicas para trabalhar janelas de navegador. Com este módulo, você pode:

• enumerar as janeals abertas atualmente
• abrir novas janelas do navegador
• criar escutas para eventos comuns de janela tais como open e close

Janelas Privadas

Se seu add-on não optou pela navegação privada, então você não verá qualquer janela de navegação privada. Janelas de navegação privada não aparecerão na propriedade browserWindows, você não receberá qualquer evento de janela, e você não será capaz de abrir janelas privadas.

Para aprender mais sobre navegação privada, como optar pela navegação privada, e como suportar navegação privada dirija-se à documentação para o módulo private-browsing.

Converção para as Janelas Chrome

Para converter do objeto BrowserWindow usando nesta API para o objeto chrome window usado na API window/utils, use a função viewFor() expotada pelo módulo viewFor().

Para converter de vola, de uma janela chrome para um objeto BrowserWindow, use a função  modelFor(), exportada pelo módulo modelFor.

Aqui está um exemplo convertendo do alto nível BrowserWindow para uma janela chrome, e então voltando para o outro modo:

var { modelFor } = require("sdk/model/core");
var { viewFor } = require("sdk/view/core");

var browserWindows = require("sdk/windows").browserWindows;

function convertToChromeAndBack(browserWindow) {
  // get the chrome window for this BrowserWindow
  var chromeWindow = viewFor(browserWindow);
  // now we can use the chrome window API
  console.log(chromeWindow.document.location.href);
  // -> "chrome://browser/content/browser.xul"

  // convert back to the high-level window
  var highLevelWindow = modelFor(chromeWindow);
  // now we can use the SDK's high-level window API
  console.log(highLevelWindow.title);
}

browserWindows.on("open", convertToChromeAndBack);

Note que acessar diretamente os objetos chrome de baixo nível significa que você não está protegido pelas garantias de compatibilidade das APIs de alto nível do SDK. Em particular, dependendo de o que você faz com estes objetos, seu código não deve trabalhar com multiprocess Firefox.

Globais

Funções

open(options)

Abre uma nova janela.

var windows = require("sdk/windows").browserWindows;

// Open a new window.
windows.open("https://www.example.com");

// Open a new window and set a listener for "open" event.
windows.open({
  url: "https://www.example.com",
  onOpen: function(window) {
    // do stuff like listen for content
    // loading.
  }
});

Retorna a janela que foi aberta:

var windows = require("sdk/windows").browserWindows;
var example = windows.open("https://www.example.com");

require("sdk/ui/button/action").ActionButton({
  id: "read",
  label: "Read",
  icon: "./read.png",
  onClick: function() {
    example.close();
  }
});

Parâmetros

options : object
Opções requeridas:

Opções opcionais:

Retorna

BrowserWindow :

Properties

browserWindows

browserWindows fornece acesso a todas as janelas de navegadores abertas com os objetos BrowserWindow.

var windows = require("sdk/windows");
for (let window of windows.browserWindows) {
  console.log(window.title);
}

console.log(windows.browserWindows.length);

Este objeto emite todos os eventos listados na seção "Eventos':

var windows = require("sdk/windows").browserWindows;

// add a listener to the 'open' event
windows.on('open', function(window) {
  myOpenWindows.push(window);
});

// add a listener to the 'close' event
windows.on('close', function(window) {
  console.log("A window was closed.");
});

// add a listener to the 'activate' event
windows.on('activate', function(window) {
  console.log("A window was activated.");
});

// add a listener to the 'deactivate' event
windows.on('deactivate', function(window) {
  console.log("A window was deactivated.");
});

A janela ativa atual é data pelo BrowserWindows.activeWindow:

var windows = require("sdk/windows").browserWindows;

windows.on('activate', function(window) {
  console.log("A window was activated.");
  var activeWindowTitle = windows.activeWindow.title;
  console.log("Active window title is: " + activeWindowTitle);
});

Eventos

open

Evento emitido quando uma nova janela é aberta. Isso não significa que o conteúdo foi carregado, somente que a janela do navegador por si só está inteiramente visível ao usuário.

Argumentos

Window : Escutas são passadas para o objeto window que desencadeou o evento.

close

Evento emitido quando uma janela é fechada. Você não pode sempre confiar na recepção do evento close para todas as janelas abertas. Em particular, se o usuário fechar o navegador de forma preciptada o que pode fechar o add-on antes das janelas serem fechadas.

Argumentos

Window : escutas são passadas para o objeto window lançou o evento.

activate

Evento emitido quando uma janela inativa é tornada ativa.

Argumentos

Window : Escutas são passadas para o objeto window que torna ativa.

deactivate

Evento emitido quando a janela ativa se torna inativa.

Arguments

Window : Escutas são passadas para o objeto window que se tornou inativa.

BrowserWindow

Uma instância BrowserWindow representa uma única janela aberta. Elas podem ser recuperadas da propriedade browserWindows exportadas pelo módulo.

var windows = require("sdk/windows").browserWindows;

//Print how many tabs the current window has
console.log("The active window has " +
            windows.activeWindow.tabs.length +
            " tabs.");

// Print the title of all browser windows
for (let window of windows) {
  console.log(window.title);
}

// close the active window
windows.activeWindow.close(function() {
  console.log("The active window was closed");
});

Métodos

activate()

Torna a janela ativa, que focará aquela janela e trará ela para o primeiro plano.

close(callback)

Fecha a janela.

Parâmetros

callback : function
Uma função chamada quando a janela termina seu processo de fechamento. É um argumento opcional.

Propriedades

title

O título atual da janela. Normalmente o título da tab ativa, mais um identificador da app. Esta propriedade é somente leitura.

tabs

Uma lista ao vivo das tabs na janela. Esse objeto tem as mesma interface da API tabs, exceto que ele contem somente as tabs nesta janela, não todas as tabs em todas as janelas. Esta propriedade é somente leitura.