<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" xmlns:xi="http://www.w3.org/2001/XInclude" type="topic" style="task" id="hellognome.js" xml:lang="pt-BR">
  <info>
    <link type="guide" xref="beginner.js#tutorials"/>
    <revision version="0.1" date="2012-07-17" status="draft"/>

    <credit type="author copyright">
      <name>Taryn Fox</name>
      <email its:translate="no">jewelfox@fursona.net</email>
      <years>2012</years>
    </credit>

    <desc>Seu primeiro aplicativo do GNOME!</desc>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Rafael Ferreira</mal:name>
      <mal:email>rafael.f.f1@gmail.com</mal:email>
      <mal:years>2013</mal:years>
    </mal:credit>
  </info>

  <title>1. Olá, GNOME!</title>
  <synopsis>
    <p>Este tutorial vai mostrar como escrever o seu primeiro aplicativo do GNOME em JavaScript. Você vai usar o JavaScript para escrever para o GNOME da mesma forma que você faria para a web. Em seguida, você aprenderá como usar widgets "nativos", para escrever aplicativos que parecem com outros aplicativos do GNOME.</p>
    <note style="warning"><p>Você instalou o GNOME no seu computador e configurou o <link xref="set-up-gedit.js">gedit</link> para com ele escrever códigos? Você vai querer fazer essas coisas primeiro.</p></note>
  </synopsis>

  <links type="section"/>

  <section id="webapp">
    <title>Vamos começar com uma página web</title>

    <p>Aqui estão alguns códigos básicos de HTML, CSS e JavaScript. Eles parecem familiar?</p>
    <code mime="application/javascript" style="numbered">
&lt;!DOCTYPE html&gt;
&lt;html&gt;
    &lt;head&gt;
        &lt;title&gt;Olá, GNOME!&lt;/title&gt;

        &lt;!-- Usa o JavaScript para mostrar os comprimentos quando alguém clica o botão --&gt;
        &lt;script type="application/javascript"&gt;
        function greeting () {
            document.getElementById ("greeting").innerHTML = ("O hai!");
        }
        &lt;/script&gt;

        &lt;!-- Estilo bem básico de CSS usando a fonte do GNOME --&gt;
        &lt;style type="text/css"&gt;
            body {
                font-face: Cantarell, sans-serif;
                text-align: center; }
        &lt;/style&gt;

    &lt;/head&gt;
    &lt;body&gt;
        &lt;br /&gt; &lt;br /&gt;
        &lt;button type="button" onclick="greeting()"&gt;Olá, GNOME!&lt;/button&gt;

        &lt;!-- Um elemento H1 vazio é preenchido quando o botão for clicado --&gt;
        &lt;h1 id="greeting"&gt;&lt;/h1&gt;
    &lt;/body&gt;
&lt;/html&gt;
</code>

    <p>Vamos salvar isso como <file>hellognome.html</file> e vejamos com o que ele se parece quando nós executamo-o!</p>

    <media type="image" mime="image/png" src="media/hellognomewebapp.png"/>

    <p>Você <em>pode</em> executar o código acima abrindo <file>hellognome.html</file> em um navegador web. Mas aqui, nós vamos criar um aplicativo do GNOME que executa nosso aplicativo web dentro dele, da mesma forma que você vê na captura de tela. Você vai poder redimensionar e maximizar a janela e clicar no X na esquina para fechá-lo, da mesma forma que você esperaria de um outro aplicativo GNOME. A diferença é que este aqui vai executar um código web dentro dele.</p>
    <p>A melhor parte? Nós vamos continuar a usar JavaScript, para escrever todas as partes que fazem do seu aplicativo funcionar com GNOME. Vamos olhar o código e ver como isso é feito!</p>
  </section>

  <section id="window">
    <title>Criando uma janela do GNOME para enquadrar nosso aplicativo web</title>

    <p>Primeiro, nós precisamos informar o GNOME que este é um aplicativo JavaScript, o qual usa gjs. Gjs é a forma do GNOMe de transformar o seu código em instruções que ele entende, de forma que esta linha sempre tem que ir no começo dos aplicativos.</p>
    <code mime="application/javascript">
#!/usr/bin/gjs
</code>
    <p>Depois disso, nós precisamos informar o GNOME quais bibliotecas nós queremos importar.</p>
    <code mime="application/javascript">
const GLib = imports.gi.GLib;
const Gtk = imports.gi.Gtk;
const Lang = imports.lang;
const Webkit = imports.gi.WebKit;
</code>
    <p>Da mesma forma que as bibliotecas complementares tipo jQuery nos permitem fazer coisas com JavaScript, cada um destas bibliotecas nos dá novas capacidades para nossos aplicativos do GNOME:</p>
    <steps>
      <item><p>O <file>Gtk</file> e <file>Lang</file> são partes básicas de qualquer aplicativo do GNOME o que permite que você cria janelas e widgets e vincula-as.</p></item>
      <item><p>O <file>GLib</file> é uma biblioteca de ajuda, o que nos permite fazer coisas como informar o GNOME onde o arquivo <file>hellognome.html</file> foi criado.</p></item>
      <item><p>E o <file>Webkit</file> é um motor web de renderização, que nós vamos usar para basicamente criar uma janela de navegador para abrir o nosso arquivo HTML.</p></item>
    </steps>

    <p>Nós vamos criar o aplicativo em si:</p>
    <code mime="application/javascript">
const HelloGNOME = new Lang.Class ({
    Name: 'Olá, GNOME',
</code>
    <p>Isso vai parecer familiar para você se você trabalhou antes com JavaScript orientado a objeto. É isso mesmo; todo o seu aplicativo é uma classe chamada HelloGNOME. E como você pode ver, nós damos a ela uma propriedade que informa qual o nome e do aplicativo.</p>

    <code mime="application/javascript">
    // Cria o aplicativo em si
    _init: function () {
        this.application = new Gtk.Application ();

        // Conecta os sinais 'activate' e 'startup' às funções de chamada
        this.application.connect('activate', Lang.bind(this, this._onActivate));
        this.application.connect('startup', Lang.bind(this, this._onStartup));
    },

    // Função de chamada para o sinal 'activate' apresenta janelas quando ativa
    _onActivate: function () {
        this._window.present ();
    },

    // Função de chamada para o sinal 'startup' constrói a interface gráfica
    _onStartup: function () {
        this._buildUI ();
    },
</code>
    <p>Aqui está um código que você que você vai copiar para quase todo aplicativo JavaScript que você construir. Ele cria um novo Aplicativo e, então, vincula seus sinais de ativação e inicialização a funções que fazem a janela se mostrar e construir sua interface gráfica, respectivamente.</p>
    <p>O que isso significa? Bom, tudo em um aplicativo do GNOME envia um sinal quando alguma coisa de importante acontece. Um botão pode enviar o sinal de clicado quando você clica nele, por exemplo. Nosso trabalho é conectar os sinais às funções que lidam com eles e fazer as coisas que nós queremos que ocorram. Nós fazemos isso usando método de conexão de objeto, o qual leva dois argumentos: O sinal que nós queremos lidar e a função Lang.bind, a qual nós temos que usar para informar a conexão qual a função nós queremos que lide com o sinal.</p>
    <p>Neste caso, nós queremos que o _onActivate lide com o sinal de ativação e que o _onStartup lide com o sinal de inicialização. O _onActivate apenas informa à janela para se apresentar; então, basicamente, quando você pressiona <keyseq><key>Alt</key> <key>Tab</key></keyseq>, o aplicativo aparece, como você esperaria. O _onStartup chama _buildUI, a qual é a função que cria nossa interface gráfica e é a próxima parte que vamos olhar.</p>
    <note style="tip"><p>Quando você copiar e colar o código acima para nossos aplicativos, certifique-se de alterar o nome para um único a cada vez.</p></note>
  </section>

  <section id="ui">
    <title>Desenhando a interface gráfica da nossa janela</title>
    <p>Na função _buildUI, nós vamos informar o GNOME sobre nossa janela e as coisas dentro dela, uma coisa de cada vez. Depois disso, nós vamos conectar tudo e colocar na exibição.</p>

    <code mime="application/javascript">
    // Constrói a interface gráfica do aplicativo
    _buildUI: function () {

        // Cria a janela do aplicativo
        this._window = new Gtk.ApplicationWindow  ({
            application: this.application,
            title: "Bem-vindo ao GNOME",
            default_height: 200,
            default_width: 400,
            window_position: Gtk.WindowPosition.CENTER });
</code>

    <p>O primeiro objeto que nós criamos é uma ApplicationWindow. Ele precisa de um título para a barra de título e a propriedade do seu aplicativo precisa ser o aplicativo que nós criamos, acima. Além disso, há várias formas de personalizar sua a aparência, o que será tratado na página de referência <link xref="GtkApplicationWindow.js">ApplicationWindow</link> em mais detalhes. Como você pode ver aqui, nós damos a ele uma altura e largura (medidas em pixels) e informamos ao GNOME que nós queremos que nossa janela apareça no centro da janela.</p>
    <code mime="application/javascript">
        // Cria um webview para mostrar o aplicativo web
        this._webView = new Webkit.WebView ();

        // Coloca o aplicativo web no webview
        this._webView.load_uri (GLib.filename_to_uri (GLib.get_current_dir() +
            "/hellognome.html", null));
</code>
    <p>Lembra-se que nós importamos o Webkit bem no começo? Aqui nós estamos criando uma nova instância de uma classe do Webkit chamada WebView, a qual é mais ou menos como uma janela de navegador que nós podemos colocar as coisas dentro do seu aplicativo. Depois disso, nós podemos, então, informar a URI que nós queremos carregar quando o aplicativo inicia.</p>
    <p>Nós <em>poderíamos</em> simplesmente informar uma URI web, como <link href="http://gnome.org">http://gnome.org</link>. Em vez disso, aqui nós usamos algumas funções de apoio do GLib para informar o WebView onde nosso arquivo <file>hellognome.html</file> está. O GLib.get_current_dir retorna o diretório no qual nosso aplicativo está sendo executado e GLib.filename_to_uri transforma nosso caminho e nome de arquivo em uma URI que a função load_uri do WebView entende. (o segundo parâmetro do filename_to_uri deveria ser nulo, a menos que você saiba para que serve e tenha um motivo para alterá-lo.)</p>
    <code mime="application/javascript">
        // Coloca o webview na janela
        this._window.add (this._webView);

        // Mostra a janela e todos seus widgets filhos
        this._window.show_all();
    },

});
</code>
    <p>Cada janela pode conter um, e apenas um, widget. Normalmente, nós usamos um contêiner de widgets, como uma <link xref="grid.js">Grid</link>, para colocar múltiplos widgets dentro e, então, usar a função de adicionar da janela para adicionar a Grid a ela. Aqui, nós precisamos apenas do WebView, de forma que é tudo que nós adicionamentos à janela. Depois disso, como a última parte da função _buildUI que cria nossa janela, nós informamos à janela para se mostrar e também mostrar o seu conteúdo.</p>
    <code mime="application/javascript">
// Executa o aplicativo
let app = new HelloGNOME ();
app.application.run (ARGV);
</code>
    <p>Finalmente, nós criamos uma nova instância de nossa classe HelloGNOME e informamos ao GNOME para executá-la.</p>
  </section>

  <section id="run">
    <title>Executando seu aplicativo do GNOME</title>

    <p>Agora que nós criamos nosso primeiro aplicativo do GNOME, é hora de testá-lo! Você não precisa compilar o seu aplicativo ou instalar qualquer software especial para isso; O GNOME possui gjs embutido, para permiti-lo executar o GNOME Shell. Basta salvar o <file>hellognome.html</file> e o aplicativo, <file>hellognome.js</file>, em um diretório que você pode obter com o terminal. (Eles normalmente abrem na sua pasta pessoal, aquela que tem o mesmo nome do seu usuário.) Depois disso, abra um terminal e digite:</p>
    <screen> <output style="prompt">$ </output>gjs hellognome.js </screen>
    <p>Você deveria ver mais ou menos a mesma captura de tela de antes, com um botão que você possa clicar para fazer uma curta mensagem aparecer.</p>

    <note style="tip">
        <p>Você pode usar comando de terminal</p>
        <screen> <output style="prompt">$ </output>cd <var>(nome do diretório)</var> </screen>
        <p>para navegar entre diretórios dentro do Terminal, para chegar onde você salvou o arquivo. Há também uma extensão para o Nautilus, o gerenciador de arquivos do GNOME, que permite que você clique com botão direito do mouse em qualquer lugar nele para abrir uma janela de terminal ali mesmo. Verifique no aplicativo que você usa para instalar novos softwares (tipo Adicionar ou Remover Programas ou Central de Programas) pela extensão.</p>
    </note>
  </section>

  <section id="whatsnext">
    <title>O que vem em seguida?</title>

    <p><link xref="02_welcome_to_the_grid.js">Continue com o próximo tutorial</link> para aprender a criar aplicativos "nativos" do GNOME que se parecem com os outros, em vez de um webview com código HTML inserido. Ou veja algumas <link xref="beginner.js#samples">amostras de código</link>, se você gostaria de ver um código exemplo para widget Gtk.</p>
    <p>Finalmente, se você deseja apenas construir aplicativos do GNOME usando bibliotecas do JavaScript projetadas para web, você pode basicamente parar aqui e fazer mais nada! Veja <link xref="beginner.js#tutorials">os últimos tutoriais</link>, se você gostaria de ver como criar um arquivo .desktop para seu aplicativo, o que vai permiti-lo aparecer no seu menu de Atividades do seu computador com todos os seus outros aplicativos.</p>
  </section>

  <section id="complete">
    <title>Amostra de código completo</title>
<code mime="application/javascript" style="numbered">#!/usr/bin/gjs

imports.gi.versions.Gtk = '3.0';

const GLib = imports.gi.GLib;
const Gtk = imports.gi.Gtk;
const Webkit = imports.gi.WebKit;

class HelloGNOME {

    // Create the application itself
    constructor() {
        this.application = new Gtk.Application ();

        // Connect 'activate' and 'startup' signals to the callback functions
        this.application.connect('activate', this._onActivate.bind(this));
        this.application.connect('startup', this._onStartup.bind(this));
    }

    // Callback function for 'activate' signal presents windows when active
    _onActivate() {
        this._window.present();
    }

    // Callback function for 'startup' signal builds the UI
    _onStartup() {
        this._buildUI();
    }

    // Build the application's UI
    _buildUI() {

        // Create the application window
        this._window = new Gtk.ApplicationWindow  ({
            application: this.application,
            title: "Welcome to GNOME",
            default_height: 200,
            default_width: 400,
            window_position: Gtk.WindowPosition.CENTER });

        // Create a webview to show the web app
        this._webView = new Webkit.WebView ();

        // Put the web app into the webview
        this._webView.load_uri (GLib.filename_to_uri (GLib.get_current_dir() +
            "/hellognome.html", null));

        // Put the webview into the window
        this._window.add (this._webView);

        // Show the window and all child widgets
        this._window.show_all();
    }

};

// Run the application
let app = new HelloGNOME ();
app.application.run (ARGV);
</code>
  </section>
</page>