Taryn Fox
jewelfox@fursona.net 2012
Crie Buttons e outros widgets que fazem coisas quando clicados.
Rafael Fontenelle
rafaelff@gnome.org 2013, 2018

# 3. Obtendo o Signal

        No último tutorial, nós aprendemos como criar widgets tipo Labels (rótulos), Images (imagens) e Buttons (botões). Aqui, nós vamos aprender como fazer para Buttons e outros widgets de entrada realmente fazer as coisas, escrevendo funções que lidam com os sinais que elas enviam quando elas são clicadas ou recebem interação.

# Um aplicativo básico

No GNOME, widgets com os quais você pode interagir, como Buttons e Switches, enviam sinais quando são clicados ou ativados. Um Button, por exemplo, envia o sinal de “clicado” quando alguém clica nele. Quando isto acontece, o GNOME procura a parte do código que diz o que deve ser feito.

Como nós vamos escrever esse código? Conectando aquele sinal de “clicado” do Button a uma função de chamada, que é uma função que você escreve apenas para lidar com esse sinal. Então, quando você aplica aquele sinal, a função conectada a ele será executada.

Aqui está um exemplo extremamente básico:

Esse ApplicationWindow possui um Button e um Label, organizados em uma Grid. Quando o Button é clicado, uma variável que mantém o número de cookies é incrementada em 1 e o Label que mostra quantos cookies existem será atualizado.

Os cookies neste exemplo não são os mesmos que aqueles que você obtém de sites, que armazenam a informação da sua sessão e podem manter rastro de quais sites você visitou. Eles são apenas biscoitos imaginários. Você pode preparar alguns de verdade, se quiser.

Aqui está o código básico, padrão que vai na inicialização do aplicativo, antes de começar a criação da janela e widgets. Além do aplicativo ter um nome único, a maior alteração em relação ao padrão é que nós criamos uma variável global bem perto do começo, para manter o número de cookies.

#!/usr/bin/gjs

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

// Nós começamos com 0 cookies var cookies = 0;

class GettingTheSignal { // Cria o aplicativo em si constructor() { this.application = new Gtk.Application();

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

// Função de chamada para o sinal "activate" apresenta uma janela quando ativa _onActivate() { this._window.present(); }

// Função de chamada para o sinal "startup" constrói a UI _onStartup() { this._buildUI (); }

Dê uma olhada na parte que usa o método de conexão do nosso aplicativo e bind, para conectar seus sinais de ativação e inicialização à função que apresenta a janela e constrói a interface gráfica. Nós vamos fazer a mesma coisa com o nosso Button quando nós chegarmos nele, porém nós vamos conectar o seu sinal de “clicado”.

# Clicando no botão

Como de costume, não colocamos todo o código para criar um Button e outros widgets dentro da função _buildUI, a qual é chamada quando o aplicativo é iniciado.

// Compila a interface de usuário do aplicativo _buildUI() {

Primeiro, nós criamos a janela em si:

// Cria a janela do aplicativo this._window = new Gtk.ApplicationWindow({ application: this.application, window_position: Gtk.WindowPosition.CENTER, default_height: 200, default_width: 400, title: "Clique no botão para obter um cookie!"});

Note que nós definimos as propriedades de seus default_height e default_width. Estes permite que nós controlemos o quão alto e largo o ApplicationWindow será, em pixels.

A seguir, nós vamos criar o Label que nos mostra o número de cookies. Nós podemos usar as variáveis de cookies como parte da propriedade do rótulo do Label.

// Cria o rótulo this._cookieLabel = new Gtk.Label ({ label: "Número de cookies: " + cookies });

Agora nós vamos criar o Button. Nós defimos a propriedade do rótulo para mostrar o texto que nós queremos no Button e nós conectamos seu sinal de “clicado” a uma função chamada _getACookie, a qual nós vamos escrever após nós terminarmos a construção da interface gráfica do nosso aplicativo.

// Cria o botão do cookie this._cookieButton = new Gtk.Button ({ label: "Obter um cookie" });

// Conecta o botão do cookie à função que lida o clique nele this._cookieButton.connect ('clicked', this._getACookie.bind(this));

Finalmente, nós criamos uma Grid, anexamos os Label e Button a ela e adicionamos-na à janela e informamos à janela para mostrar a si e a seu conteúdo. Isso é tudo que nós precisamos dentro da função _buildUI, de forma que nós fechamos-a com chaves, assim como uma vírgula que informa ao GNOME para continuar para a próxima função. Note que ainda que nós tenhamos escrito o código para o primeiro Label, nós ainda podemos anexá-lo à Grid de uma forma que vai colocá-lo na parte inferior.

// Cria uma grade para organizar tudo dentro this._grid = new Gtk.Grid ({ halign: Gtk.Align.CENTER, valign: Gtk.Align.CENTER, row_spacing: 20 });

// Coloca tudo dentro da grade this._grid.attach (this._cookieButton, 0, 0, 1, 1); this._grid.attach (this._cookieLabel, 0, 1, 1, 1);

// Adiciona a grade à janela this._window.add (this._grid);

// Mostra a janela e todos os widgets filhos this._window.show_all();

}

Agora, nós escrevemos a função _getACookie. Quando nosso Button envia seu sinal de “clicado”, o código nesta função vai ser executado. Neste caso, tudo que isso faz é aumentar o número de cookies em 1 e atualizar o Label para mostrar o novo número de cookies. Nós fazemos isso usando o método set_label do Label.

Muitos widgets têm as mesmas propriedades e métodos. Ambos Labels e Buttons, por exemplo, tem uma propriedade de rótulo que informa que texto está dentro dele e métodos get_label e set_label que permitem a você verificar o que este texto é e alterá-lo, respectivamente. Então, se você aprende como um widget funciona, você também vai saber como outros como ele funcionam.

_getACookie: function() {

// Aumenta o número de cookies em 1 e atualiza o rótulo cookies++; this._cookieLabel.set_label ("Número de cookies: " + cookies);

}

};

Finalmente, nós executamos o aplicativo, usando o mesmo tipo de código de nosso último tutorial.

// Executa o aplicativo let app = new GettingTheSignal (); app.application.run (ARGV);

# Ligando o switch

Os botões não são os únicos widgets de entrada na nossa caixa de ferramentas do GTK+. Também podemos usar switches (interruptores), como o deste exemplo. Os switches não têm uma propriedade de rótulo, por isso, temos que criar um rótulo separado que diga o que fazer para ir ao lado dele.

Um Switch tem duas posições, desligado (Off) e ligado (On). Quando um Switch está ativado, o texto e a cor do plano de fundo mudam, para que você possa identificar em que posição está.

Você pode ter visto Switches como esses no menu de acessibilidade do GNOME, que permite ativar e desativar recursos como texto grande e o teclado na tela. Neste caso, o Switch controla nosso dispensador de cookie imaginário. Se o Comutador estiver ativado, você poderá obter cookies clicando no botão “Obter um cookie”. Se estiver desligado, clicar no botão não fará nada.

Você pode acessar o menu de acessibilidade clicando no contorno de um ser humano, próximo ao seu nome no canto superior direito da tela.

Veja como nós criamos o Switch:

// Cria um switch que controla se você pode ou não ganhar this._cookieSwitch = new Gtk.Switch ();

Na verdade, não precisamos conectar o Switch a nada. Tudo o que precisamos fazer é escrever uma declaração if em nossa função _getACookie, para verificar se o Switch está ativado. Se quiséssemos fazer algo acontecer assim que você ligasse o Switch, nós conectaríamos o sinal notify::active, assim:

// Conecta o switch à função que lida com ele this._cookieSwitch.connect ('notify::active', this._cookieDispenser.bind(this));

Um Switch está definido para a posição desligada por padrão. Se quiséssemos que o Switch inciasse ligado, definiríamos o valor de sua propriedade ativa como “true” quando o criamos.

this._cookieSwitch = new Gtk.Switch ({ active: true });

Vamos apenas criá-lo normalmente, e então criar o Label que o acompanha. Queremos que o Switch e o Label sejam mantidos próximos uns dos outros, então criaremos um Grid apenas para eles, e então colocaremos esse Grid em nosso Grid maior que contém todos os widgets dentro dele. Veja como é o código para criar tudo isso:

// Cria o switch que controla se você pode ou não ganhar this._cookieSwitch = new Gtk.Switch ();

// Cria o rótulo para ir com o switch this._switchLabel = new Gtk.Label ({ label: "Cookie dispenser" });

// Cria uma grade para o switch e seu rótulo this._switchGrid = new Gtk.Grid ({ halign: Gtk.Align.CENTER, valign: Gtk.Align.CENTER });

// Coloca seu switch e seu rótulo dentro daquela grade this._switchGrid.attach (this._switchLabel, 0, 0, 1, 1); this._switchGrid.attach (this._cookieSwitch, 1, 0, 1, 1);

E agora nós organizamos tudo na Grad maior assim.

// Coloca tudo dentro da grade this._grid.attach (this._cookieButton, 0, 0, 1, 1); this._grid.attach (this._switchGrid, 0, 1, 1, 1); this._grid.attach (this._cookieLabel, 0, 2, 1, 1);

Agora, alteramos a função _getACookie para verificar se o fornecedor de cookie está ativado. Fazemos isso usando o método get_active do Switch. Retorna “true” se o Switch estiver ligado e “false” se o Switch estiver desligado.

Quando um método é usado em uma instrução if como essa, o código dentro da instrução if é executado se o método retornar “true”.

_getACookie() {

// O fornecedor de cookie está ligado? if (this._cookieSwitch.get_active()) {

// Aumenta o número de cookies em 1 e atualiza o rótulo cookies++; this._cookieLabel.set_label ("Número de cookies: " + cookies);

}

}

# Sintonizando o rádio

Outro tipo de widget de entrada que podemos usar é chamado de RadioButton, normalmente conhecido em português como “botão de opção”. Você os cria em grupos e, em seguida, apenas um RadioButton em um grupo pode ser selecionado por vez. Eles são chamados de RadioButtons porque funcionam como o botão de pré-seleção de canais em rádios de carros antigos. O rádio só podia ser sintonizado em uma estação de cada vez, então, sempre que você pressionasse um botão, outro retornaria para o estado de não pressionado.

Primeiramente, vamos alterar o nome do nosso ApplicationWindow e aumentar sua propriedade border_width, para que nossos widgets não sejam muito compactados. A border_width é o número de pixels entre qualquer widget e a borda da janela.

// Cria a janela do aplicativo this._window = new Gtk.ApplicationWindow({ application: this.application, window_position: Gtk.WindowPosition.CENTER, default_height: 200, default_width: 400, border_width: 20, title: "Escolha o com nome 'cookie'!"});

Depois disso, criamos os RadioButtons. Lembre-se de como eles são criados em grupos? A maneira como fazemos isso, é definir cada nova propriedade de grupo RadioButton para o nome de outro RadioButton.

// Cria os botões de opção this._cookieRadio = new Gtk.RadioButton ({ label: "Cookie" }); this._notCookieOne = new Gtk.RadioButton ({ label: "Não um cookie", group: this._cookieRadio }); this._notCookieTwo = new Gtk.RadioButton ({ label: "Não um cookie", group: this._cookieRadio });

Em seguida, criamos uma grade para os RadioButtons. Lembre-se, não precisamos organizar as coisas em Grids na mesma ordem em que as criamos.

// Ordenamos os botões de opção na sua própria grade this._radioGrid = new Gtk.Grid (); this._radioGrid.attach (this._notCookieOne, 0, 0, 1, 1); this._radioGrid.attach (this._cookieRadio, 0, 1, 1, 1); this._radioGrid.attach (this._notCookieTwo, 0, 2, 1, 1);

Normalmente, o RadioButton selecionado por padrão é aquele que é o nome do grupo. Queremos que o primeiro botão “Não um cookie” esteja selecionado por padrão, motivo pelo qual usamos o método set_active.

Poderíamos também definir sua propriedade ativa como “true” quando a criamos.

// Define o botão que estará no topo como estando ativo por padrão this._notCookieOne.set_active (true);

Agora nós organizamos tudo em nossa Grid principal como de costume …

// Coloca tudo dentro da grade this._grid.attach (this._radioGrid, 0, 0, 1, 1); this._grid.attach (this._cookieButton, 0, 1, 1, 1); this._grid.attach (this._cookieLabel, 0, 2, 1, 1);

Em seguida, alteramos nossa função _getACookie para testar se o botão do cookie é o selecionado.

_getACookie() {

// Você selecionou "cookie" em vez de "não um cookie"? if (this._cookieRadio.get_active()) {

// Aumenta o número de cookies em 1 e atualiza o rótulo cookies++; this._cookieLabel.set_label ("Número de cookies: " + cookies);

}

}

# Você consegue escrever “cookie”?

O último widget de entrada que vamos cobrir é o widget Entry, que é usado para entrada de texto de linha única.

Se você precisar inserir um parágrafo inteiro ou mais, como se estivesse construindo um editor de texto, você vai querer dar uma olhada no widget muito mais personalizável TextView.

Depois de alterar o nome da janela, criamos o widget Entry.

// Cria um novo campo de entrada de texto this._spellCookie = new Gtk.Entry ();

Em seguida, organizamos tudo na Grid …

// Coloca tudo dentro da grade this._grid.attach (this._spellCookie, 0, 0, 1, 1); this._grid.attach (this._cookieButton, 0, 1, 1, 1); this._grid.attach (this._cookieLabel, 0, 2, 1, 1);

E agora nós modificamos a instrução if do _getACookie novamente, usando o método get_text do Entry para recuperar o texto que você inseriu nele e ver se você digitou “cookie” corretamente. Não nos importamos se você capitaliza “cookie” ou não, então usamos o método embutido toLowerCase do JavaScript para alterar o todo texto do Entry para minúsculo dentro da instrução if.

Um widget de Entry não possui uma propriedade de rótulo, que é uma string definida que o usuário não pode alterar. (Você não pode normalmente alterar o rótulo em um Button, por exemplo). Em vez disso, ele tem uma propriedade de texto, que muda para corresponder ao que o usuário digita.

_getACookie() {

// Você escreveu "cookie" corretamente? if ((this._spellCookie.get_text()).toLowerCase() == "cookie") {

// Aumenta o número de cookies em 1 e atualiza o rótulo cookies++; this._cookieLabel.set_label ("Número de cookies: " + cookies);

}

}

# O que vem em seguida?

Continue lendo, se você quiser ver o código completo para cada versão do nosso aplicativo de criador de cookies.

A página principal de tutoriais em JavaScript possui amostras de código mais detalhadas para cada widget de entrada, incluindo vários não abordados aqui.

# Amostra de código completo

## Amostra de código com Button

#!/usr/bin/gjs

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

// Começamos com 0 cookies var cookies = 0;

class GettingTheSignal {

// Cria o aplicativo em si constructor() { this.application = new Gtk.Application();

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

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

// Função de chamada para o sinal 'startup' constrói a interface gráfica _onStartup() { this._buildUI(); }

// Constrói a interface gráfica do aplicativo _buildUI() {

// Cria a janela do aplicativo this._window = new Gtk.ApplicationWindow({ application: this.application, window_position: Gtk.WindowPosition.CENTER, default_height: 200, default_width: 400, title: "Clique no botão para obter um cookie!"});

// Cria o rótulo this._cookieLabel = new Gtk.Label ({ label: "Número de cookies: " + cookies });

// Cria o botão de cookie this._cookieButton = new Gtk.Button ({ label: "Obtenha um cookie" });

// Conecta o botão de cookie à função que lida com clicar nele this._cookieButton.connect ('clicked', this._getACookie.bind(this));

// Cria uma grade que organiza tudo dentro this._grid = new Gtk.Grid ({ halign: Gtk.Align.CENTER, valign: Gtk.Align.CENTER, row_spacing: 20 });

// Coloca tudo dentro da grade this._grid.attach (this._cookieButton, 0, 0, 1, 1); this._grid.attach (this._cookieLabel, 0, 1, 1, 1);

// Adiciona a grade à janela this._window.add (this._grid);

// Mostra a janela e todos os widgets filhos this._window.show_all();

}

_getACookie() {

// Aumenta o número de cookies por 1 e atualiza o rótulo cookies++; this._cookieLabel.set_label ("Número de cookies: " + cookies);

}

};

// Executa o aplicativo let app = new GettingTheSignal (); app.application.run (ARGV);

## Amostra de código com Switch

#!/usr/bin/gjs

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

// Nós começamos com 0 cookies var cookies = 0;

class GettingTheSignal {

// Cria o aplicativo em si constructor() { this.application = new Gtk.Application();

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

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

// Função de chamada para o sinal 'startup' constrói a interface gráfica _onStartup() { this._buildUI(); }

// Constrói a interface gráfica do aplicativo _buildUI() {

// Cria a janela do aplicativo this._window = new Gtk.ApplicationWindow({ application: this.application, window_position: Gtk.WindowPosition.CENTER, default_height: 200, default_width: 400, title: "Clique no botão para obter um cookie!"});

// Cria o rótulo this._cookieLabel = new Gtk.Label ({ label: "Número de cookies: " + cookies });

// Cria o botão de cookie this._cookieButton = new Gtk.Button ({ label: "Obter um cookie" });

// Conecta o botão do cookie à função que lida o clique nele this._cookieButton.connect ('clicked', this._getACookie.bind(this));

// Cria um switch que controla se você pode ou não ganhar this._cookieSwitch = new Gtk.Switch ();

// Cria o rótulo para ir com o switch this._switchLabel = new Gtk.Label ({ label: "Cookie dispenser" });

// Cria uma grade para o switch e seu rótulo this._switchGrid = new Gtk.Grid ({ halign: Gtk.Align.CENTER, valign: Gtk.Align.CENTER });

// Coloca seu switch e seu rótulo dentro daquela grade this._switchGrid.attach (this._switchLabel, 0, 0, 1, 1); this._switchGrid.attach (this._cookieSwitch, 1, 0, 1, 1);

// Cria uma grade para organizar todo resto dentro this._grid = new Gtk.Grid ({ halign: Gtk.Align.CENTER, valign: Gtk.Align.CENTER, row_spacing: 20 });

// Coloca tudo dentro da grade this._grid.attach (this._cookieButton, 0, 0, 1, 1); this._grid.attach (this._switchGrid, 0, 1, 1, 1); this._grid.attach (this._cookieLabel, 0, 2, 1, 1);

// Adiciona a grade à janela this._window.add (this._grid);

// Mostra a janela e todos os widgets filhos this._window.show_all();

}

_getACookie() {

// O fornecedor de cookie está ligado? if (this._cookieSwitch.get_active()) {

// Aumenta o número de cookies em 1 e atualiza o rótulo cookies++; this._cookieLabel.set_label ("Número de cookies: " + cookies);

}

}

};

// Executa o aplicativo let app = new GettingTheSignal (); app.application.run (ARGV);

## Amostra de código com RadioButton

#!/usr/bin/gjs

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

// We start out with 0 cookies var cookies = 0;

class GettingTheSignal {

// 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 window 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, window_position: Gtk.WindowPosition.CENTER, default_height: 200, default_width: 400, border_width: 20, title: "Choose the one that says 'cookie'!"});

// Create the radio buttons this._cookieRadio = new Gtk.RadioButton ({ label: "Cookie" }); this._notCookieOne = new Gtk.RadioButton ({ label: "Not cookie", group: this._cookieRadio }); this._notCookieTwo = new Gtk.RadioButton ({ label: "Not cookie", group: this._cookieRadio });

// Arrange the radio buttons in their own grid this._radioGrid = new Gtk.Grid (); this._radioGrid.attach (this._notCookieOne, 0, 0, 1, 1); this._radioGrid.attach (this._cookieRadio, 0, 1, 1, 1); this._radioGrid.attach (this._notCookieTwo, 0, 2, 1, 1);

// Set the button that will be at the top to be active by default this._notCookieOne.set_active (true);

// Create the cookie button this._cookieButton = new Gtk.Button ({ label: "Get a cookie" });

// Connect the cookie button to the function that handles clicking it this._cookieButton.connect ('clicked', this._getACookie.bind(this));

// Create the label this._cookieLabel = new Gtk.Label ({ label: "Number of cookies: " + cookies });

// Create a grid to arrange everything inside this._grid = new Gtk.Grid ({ halign: Gtk.Align.CENTER, valign: Gtk.Align.CENTER, row_spacing: 20 });

// Put everything inside the grid this._grid.attach (this._radioGrid, 0, 0, 1, 1); this._grid.attach (this._cookieButton, 0, 1, 1, 1); this._grid.attach (this._cookieLabel, 0, 2, 1, 1);

// Add the grid to the window this._window.add (this._grid);

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

}

_getACookie() {

// Did you select "cookie" instead of "not cookie"? if (this._cookieRadio.get_active()) {

// Increase the number of cookies by 1 and update the label cookies++; this._cookieLabel.set_label ("Number of cookies: " + cookies);

}

}

};

// Run the application let app = new GettingTheSignal (); app.application.run (ARGV);

## Code sample with Entry

#!/usr/bin/gjs

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

// We start out with 0 cookies var cookies = 0;

class GettingTheSignal {

// 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 window 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, window_position: Gtk.WindowPosition.CENTER, default_height: 200, default_width: 400, border_width: 20, title: "Spell 'cookie' to get a cookie!"});

// Create the text entry field this._spellCookie = new Gtk.Entry ();

// Create the cookie button this._cookieButton = new Gtk.Button ({ label: "Get a cookie" });

// Connect the cookie button to the function that handles clicking it this._cookieButton.connect ('clicked', this._getACookie.bind(this));

// Create the label this._cookieLabel = new Gtk.Label ({ label: "Number of cookies: " + cookies });

// Create a grid to arrange everything inside this._grid = new Gtk.Grid ({ halign: Gtk.Align.CENTER, valign: Gtk.Align.CENTER, row_spacing: 20 });

// Put everything inside the grid this._grid.attach (this._spellCookie, 0, 0, 1, 1); this._grid.attach (this._cookieButton, 0, 1, 1, 1); this._grid.attach (this._cookieLabel, 0, 2, 1, 1);

// Add the grid to the window this._window.add (this._grid);

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

}

_getACookie() {

// Did you spell "cookie" correctly? if ((this._spellCookie.get_text()).toLowerCase() == "cookie") {

// Increase the number of cookies by 1 and update the label cookies++; this._cookieLabel.set_label ("Number of cookies: " + cookies);

}

}

};

// Run the application let app = new GettingTheSignal (); app.application.run (ARGV);