<?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"><![CDATA[
<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <title>Hello, GNOME!</title>

        <!-- Use JavaScript to show a greeting when someone clicks the button -->
        <script type="application/javascript">
        function greeting () {
            document.getElementById ("greeting").innerHTML = ("O hai!");
        }
        </script>

        <!-- Very basic CSS style using the GNOME font -->
        <style type="text/css">
            body {
                font-face: Cantarell, sans-serif;
                text-align: center; }
        </style>

    </head>
    <body>
        <br /> <br />
        <button type="button" onclick="greeting()">Hello, GNOME!</button>

        <!-- Empty H1 element gets filled in when the button is clicked -->
        <h1 id="greeting"></h1>
    </body>
</html>
]]></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>Then we should set the versions of the libraries we'll be using.</p>
<code mime="application/javascript"><![CDATA[
imports.gi.versions.Gtk = '3.0';
imports.gi.versions.WebKit2 = '4.0';
]]></code>
    <p>Depois disso, nós precisamos informar o GNOME quais bibliotecas nós queremos importar.</p>
    <code mime="application/javascript"><![CDATA[
const GLib = imports.gi.GLib;
const Gtk = imports.gi.Gtk;
const Webkit = imports.gi.WebKit2;
]]></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><file>Gtk</file> is the basic part of any GNOME application, which lets you create windows and widgets and tie them together.</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"><![CDATA[
class HelloGNOME {
]]></code>
    <p>This will look familiar to you if you've worked with object-oriented JavaScript before. That's right; our whole application is a class called HelloGNOME.</p>

    <code mime="application/javascript"><![CDATA[
    // 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();
    }
]]></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>What does that mean? Well, everything in a GNOME application sends out a signal when something important happens. A button might send out the clicked signal when you click on it, for instance. Our job is to connect the signals to functions which handle them, and make the things that we want to have happen occur. We do this using each object's connect method, which takes two arguments: The signal we want to handle, and the bound function, which we have to use to tell connect which function we want to have handle the signal.</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>When you copy and paste the above code for your own applications, be sure to change the class name to a unique one each time.</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"><![CDATA[
    // 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 });
]]></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';
imports.gi.versions.WebKit2 = '4.0';

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

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>
