electron/docs-translations/pt-BR/tutorial/desktop-environment-integration.md

Integração com o ambiente desktop

Diferentes sistemas operacionais proveem diferentes features para integrar aplicacões desktop em seus ambientes. Por exemplo, no Windows, as aplicações podem inserir atalhos no JumpList da barra de tarefas, no Mac, aplicações podem implementar um menu customizado na dock.

Este guia explica como intregar suas aplicações no ambiente desktop com a API do Electron.

Documentos Recentes (Windows & OS X)

O Windows e o OS X disponibilizam um acesso fácil para a lista de arquivos abertos recentemente pela aplicação através do JumpList ou Dock Menu, respectivamente.

JumpList:

Dock menu da Aplicação:

Para adicionar um arquivo para os documentos recentes, você pode usar a API app.addRecentDocument:

var app = require('app');
app.addRecentDocument('/Users/USERNAME/Desktop/work.type');

E você pode usar a API app.clearRecentDocuments para limpar a lista de documentos recentes.

app.clearRecentDocuments();

Notas para Windows

A fim de ser possível usar essas funcionalidades no Windows, sua aplicação deve estar registrada como um handler daquele tipo de documento, caso contrário o arquivo não será exibido no JumpList mesmo depois de você ter adicionado isto. Você pode encontrar qualquer coisa sobre o registro da aplicacão em Application Registration.

Quando um usuário clica em um arquivo na JumpList, uma nova instância da sua aplicacão deve ser iniciada com o caminho do arquivo adicionado como um argumento de linha de comando.

Notas para OS X

Quando um arquivo for requisitado pelo menu de documentos recentes, o evento open-file do módulo app deve ser emitido.

Dock Menu customizado (OS X)

OS X permite que desenvolvedores especifiquem um menu customizado para a dock, que normalmente contém alguns atalhos para as funcionalidades mais utilizadas da sua aplicacão.

Dock menu of Terminal.app:

Para criar seu Dock Menu customizado, você pode usar a API app.dock.setMenu, ela está disponível apenas no OS X:

var app = require('app');
var Menu = require('menu');
var dockMenu = Menu.buildFromTemplate([
  { label: 'New Window', click: function() { console.log('New Window'); } },
  { label: 'New Window with Settings', submenu: [
    { label: 'Basic' },
    { label: 'Pro'}
  ]},
  { label: 'New Command...'}
]);
app.dock.setMenu(dockMenu);

Tarefas do Usuário (Windows)

No Windows você pode especificar ações customizadas na categoria Tasks do JumList, esse texto foi copiado do MSDN:

Applications define tasks based on both the program's features and the key things a user is expected to do with them. Tasks should be context-free, in that the application does not need to be running for them to work. They should also be the statistically most common actions that a normal user would perform in an application, such as compose an email message or open the calendar in a mail program, create a new document in a word processor, launch an application in a certain mode, or launch one of its subcommands. An application should not clutter the menu with advanced features that standard users won't need or one-time actions such as registration. Do not use tasks for promotional items such as upgrades or special offers.

It is strongly recommended that the task list be static. It should remain the same regardless of the state or status of the application. While it is possible to vary the list dynamically, you should consider that this could confuse the user who does not expect that portion of the destination list to change.

Tarefas do Internet Explorer:

Ao contrário do Menu Dock no OS X que é um verdadeiro menu, tarefas do usuário no Windows funcionam como atalhos, de uma forma que quando o usuário clica em uma tarefa, um programa deve ser executado com os argumentos especificados.

Para setar tarefas do usuário para sua aplicação, você pode usar a API app.setUserTasks:

var app = require('app');
app.setUserTasks([
  {
    program: process.execPath,
    arguments: '--new-window',
    iconPath: process.execPath,
    iconIndex: 0,
    title: 'New Window',
    description: 'Create a new window'
  }
]);

Para limpar sua lista de tarefas, apenas chame app.setUserTasks com um array vazio.

app.setUserTasks([]);

As tarefas do usuário são exibidas mesmo depois da aplicação ser fechada, então o ícone e o caminho programa especificado pela tarefa deve existir até sua aplicação for fechada.

Miniaturas na Barra de Ferramentas

No Windows você pode adicionar uma miniatura na barra de ferramentas com botões específicos e barra de tarefas com uma janela da aplicação. Isso provê ao usuário uma forma de acessar um comando específico da janela sem ser necessário restaurar or ativar a janela.

Isso é ilustrado no MSDN:

This toolbar is simply the familiar standard toolbar common control. It has a maximum of seven buttons. Each button's ID, image, tooltip, and state are defined in a structure, which is then passed to the taskbar. The application can show, enable, disable, or hide buttons from the thumbnail toolbar as required by its current state.

For example, Windows Media Player might offer standard media transport controls such as play, pause, mute, and stop.

Miniaturas da barra de tarefas do Windows Media Player:

Você pode usar BrowserWindow.setThumbarButtons para criar miniaturas na barra de ferramentas para sua aplicacão.

var BrowserWindow = require('browser-window');
var path = require('path');
var win = new BrowserWindow({
  width: 800,
  height: 600
});
win.setThumbarButtons([
  {
    tooltip: "button1",
    icon: path.join(__dirname, 'button1.png'),
    click: function() { console.log("button2 clicked"); }
  },
  {
    tooltip: "button2",
    icon: path.join(__dirname, 'button2.png'),
    flags:['enabled', 'dismissonclick'],
    click: function() { console.log("button2 clicked."); }
  }
]);

Para limpar os botões na miniatura da barra de ferramentas, apenas chame BrowserWindow.setThumbarButtons com um array vazio.

win.setThumbarButtons([]);

Unity Launcher Shortcuts (Linux)

No Unity, você pode adicionar entradas customizadas para estes lançadores modificando o arquivo .desktop, veja Adding Shortcuts to a Launcher.

Launcher shortcuts do Audacious:

Barra de Progresso na Barra de Tarefas (Windows & Unity)

No Windows o botão na barra de tarefas pode ser usado para exibir uma barra de progresso. Isto permite que a janela exiba informação sobre o progresso de algum progresso sem a necessidadedo usuário mudar de janela.

A Unity DE também tem uma funcionalidade parecida que permite especificar uma barra de progresso no ícone do lançador.

Barra de Progresso no botão da barra de tarefas:

Barra de progresso no Unity launcher:

Para adicionar uma barra de progresso para uma janela, você pode ver a API: To set the progress bar for a Window, you can use the BrowserWindow.setProgressBar:

var window = new BrowserWindow({...});
window.setProgressBar(0.5);

Representação do arquivo na janela (OS X)

No OS X, uma janela pode possuir a representação de um arquivo na barra de título, para que o ícone do arquivo possa ser exibido na barra de título e uma janela seja exibida quando o usuário usar um Command-Click ou Control-Click no título.

Você também pode inserir um estado de edicão na janela para que o ícone do arquivo possa indicar se o documento nesta janela foi modificado.

Menu popup da representação de arquivo:

Para inserir o arquivo de representacão da janela, você pode usar as API BrowserWindow.setRepresentedFilename e BrowserWindow.setDocumentEdited:

var window = new BrowserWindow({...});
window.setRepresentedFilename('/etc/passwd');
window.setDocumentEdited(true);