1. Introdução Desenvolvendo um sticker Componentes UI Subindo o Sticker para o Portal do Desenvolvedor...

Transcrição

1

2 1. Introdução Desenvolvo um sticker Adicionando uma página Telas de Ajuda e Copyright Eventos de tecla propagados Componentes UI Button TextField VirtualKeyboard ListMenu Navegando entre as tabs do ListMenu Subindo o Sticker para o Portal do Desenvolvedor... 25

3 1. Introdução Este tutorial tem por objetivo descrever as funcionalidades básicas do funcionamento de um Sticker, apresentando os componentes de interface do usuário necessários para desenvolver qualquer aplicativo baseado nesta tecnologia. Os componentes do Sticker foram desenvolvidos em NCLua. Por fugir do escopo deste treinamento, não iremos ensinar a linguagem NCLua. Portanto, faz-se necessário o conhecimento prévio desta linguagem para a criação de Stickers e para o entimento dos trechos de código transcritos nesta apostila.

4 2. Desenvolvo um sticker Vamos iniciar partindo de um Sticker o mais simples possível e vamos aprimorá-lo passo-a-passo. O código abaixo deverá obrigatoriamente ser salvo como main.lua, pois, este será o entry point do Sticker. Este código deve ser salvo no diretório /home/tqtvd/application. require"sticker" require"imageloader" NIMGL = imageloader.imageloader:new() stickerexemplo = sticker.sticker:new() stickerexemplo:setlabel("sticker Exemplo") stickerexemplo:setlefticon(imgl:getimage("imagens/title_icon.png")) stickerexemplo:setrighticon(imgl:getimage("imagens/home_icon.png")) stickerexemplo:start() Vamos agora executar este código de Sticker digitando a linha de comando no terminal, conforme mostrado abaixo: sh /home/tqtvd/astro.sh A tela a seguir deverá aparecer. Veja o que foi definido por nós e qual seu efeito visual.

5 stickerexemplo:setrighticon(imgl:getimage("imagens/home_icon.png")) stickerexemplo:setlabel("sticker Exemplo") stickerexemplo:setlefticon(imgl:getimage("imagens/title_icon.png")) 2.1. Adicionando uma página Todo Sticker deverá ter um componente principal que irá gerenciar todos os demais. Sua inclusão é bem simples:

6 require"sticker" require"imageloader" require"component" --*********** Criando uma página ********* dofile("mainpage.lua") pgprincipal = PaginaPrincipal:new() --**************************************** NIMGL = imageloader.imageloader:new() stickerexemplo = sticker.sticker:new() stickerexemplo:setlabel("sticker Exemplo") stickerexemplo:setlefticon(nimgl:getimage("imagens/title_icon.png")) stickerexemplo:setrighticon(nimgl:getimage("imagens/home_icon.png")) --*********** Adicionando o componente ********* stickerexemplo:setmaincomponent(pgprincipal) --************************************************ stickerexemplo:start() As linhas acima em negrito mostram os comandos necessários para adicionar o component principal em nosso arquivo main.lua. Porém, antes de executarmos, temos que criar também o arquivo mainpage.lua que é importado através do comando dofile("mainpage.lua"). O código abaixo implementa a página principal. Este código servirá como modelo para qualquer página que for criada daqui para frente. Todos os métodos deste código são obrigatórios, porém, podem e devem ser implementados conforme necessário. Iremos ver vários exemplos dessa implementação mais adiante.

7 if PaginaPrincipal then return PaginaPrincipal local public = component.component:new() PaginaPrincipal = public function public:init() function public:paint(g) --*********** Implementação do usuário **************************** g:attrcolor(239,239,239,255) g:drawrect("fill", self.x, self.y, self.width, self.height) g:attrfont("default",18,"regular") g:attrcolor(0, 0, 239, 255) g:drawtext(self.x+5,self.y+5,"página exemplo") --***************************************************************** function public:processkeyevent(evt) function public:reset() function public:setfocus(boolean) function public:notifyfirstinnerfocus() function public:notifylastinnerfocus() function public:notifynext() function public:notifyprevious()

8 mainpage.lua Toda a área em branco acima foi preenchida pelo método paint do arquivo mainpage.lua. Esta é área padrão de desenho do Sticker Telas de Ajuda e Copyright Todo Sticker responde às teclas Verde e Amarela do controle remoto chamando para cada uma um componente específico. Estas telas são obrigatoriamente as telas de Configurações (ou de Copyright, caso o Sticker não demande por parâmetros de configuração) e Ajuda, respectivamente. Vamos implementá-las em nosso arquivo main.lua conforme as linhas em negrito abaixo:

9 require"sticker" require"pagemanager" require"imageloader" require"button" dofile("mainpage.lua") dofile("helppage.lua") dofile("copyrightpage.lua") pgprincipal = PaginaPrincipal:new() pghelp = HelpPage:new() pgcopyright = CopyrightPage:new() NIMGL = imageloader.imageloader:new() stickerexemplo = sticker.sticker:new() stickerexemplo:setlabel("sticker Exemplo") stickerexemplo:setlefticon(nimgl:getimage("../gfx/title_icon.png")) stickerexemplo:setrighticon(nimgl:getimage("../gfx/home_icon.png")) stickerexemplo:setmaincomponent(pgprincipal) --*********** Adicionando a página de Help e Copyright ********* stickerexemplo:setyellowcomponent(pghelp) stickerexemplo:setgreencomponent(pgcopyright) --************************************************************** stickerexemplo:start() Os métodos setyellowcomponent(component) e setgreencomponent(component) são utilizados para definir que páginas serão chamadas ao pressionar as teclas coloridas em questão. Veja exemplos das telas de Ajuda e Copyright nas figuras a seguir. Não iremos exibir aqui o código de implementação das mesmas, pois o princípio é idêntico ao que já foi descrito. É importante saber que quando estas telas são chamadas, o método setfocus(false) da página corrente é invocado e setfocus(true) da tela seguinte é invocado. Ao pressionar novamente a tecla colorida anteriormente pressionada o processo é repetido. Desta forma, é possível tratar alguns comportamentos da página principal em meio a essa transição. Obs.: No PC as teclas coloridas VERMELHO, VERDE, AMARELO E AZUL são simuladas através das teclas F1, F2, F3 e F4 respectivamente.

10 2.3. Eventos de tecla propagados Quando o usuário chama as telas de Ajuda ou Copyright, automaticamente os eventos de tecla são propagados para o método :processkeyevent(evt) da tela ativa. No exemplo abaixo queremos chamar à atenção como esses eventos são propagados e tratados dentro da tela de Ajuda. Atente para as linhas em negrito:

11 if HelpPage then return HelpPage local public = component.component:new() HelpPage = public function public:init() --******** Implementação do usuário ******** function public:paint(g) --******** Implementação do usuário ******** function public:processkeyevent(evt) if evt == "ENTER" then self.parent:reset() return true (restante dos métodos) Todas as vezes que uma página recebe um evento, o desenvolvedor poderá decidir se o método paint() deverá ser evocado após a execução do processkeyevent(evt). Quando o processkeyevent(evt) retorna true (return true) o paint(g) será executado.

12 3. Componentes UI Descreveremos agora alguns dos componentes gráficos embarcados no Sticker. Todos os componentes e seus métodos podem ser vistos em mais detalhes através da documentação disponível aos desenvolvedores no portal de Desenvolvedores do StickerCenter. Aqui iremos apenas desmonstrar o seu funcionamento básico, que é comum a todos os Stickers. Também não iremos mais mostrar aqui a íntegra do código de cada página, somente a parte que importa para que o componente em questão seja funcional Button Um Button possui 2 imagens. Uma para seu estado normal (método :setimage(image)) e outra que será exibida quando este estiver focado (método :setfocusimage(image)). Um texto também poderá ser definido para o botão, de modo a descrever a ação daquele botão na interface. Por padrão, este texto ficará centralizado verticalmente e horizontalmente dentro da área da imagem do Button. Note que para definirmos as coordenadas do nosso Button utilizamos o self.x e self.y para que sua posição fique relativa ao Sticker. Se isto não for definido assim, não só para este, mas para todos os componentes, o comportamento durante algumas transições ou efeitos do Sticker poderá ser o não esperado. Portanto, sempre adote esta técnica. Cada componente possui seu próprio método paint(g) que dever ser evocado cada vez que quisermos desenhá-lo. No nosso exemplo, chamamos o paint(g) de nosso button dentro do paint(g) de nossa página. Adicione esta linha ao main.lua require"button" Código do arquivo mainpage.lua

13 function public:init() self.btexemplo = button.button:new() self.btexemplo:setimage(nimgl:getimage("imagens/button_off.png")) self.btexemplo:setfocusimage(nimgl:getimage("imagens/button_on.png")) self.btexemplo:setx(self.x + (self.width - self.btexemplo:getwidth())/2) self.btexemplo:sety(self.y + 45) self.btexemplo:setlabel("botão 1") self.btexemplo:setfocus(true) function public:paint(g) self.btexemplo:paint(g) Executando o código acima teremos o resultado abaixo: 3.2. TextField Um TextField é uma área de texto editável pelo usuário. Sua definição é bem intuitiva e semelhante ao que fizemos para a criação do Button no exemplo anterior. Adicione esta linha ao main.lua require"textfield" Código do arquivo mainpage.lua

14 function public:init() self.btexemplo = button.button:new() self.btexemplo:setimage(nimgl:getimage("imagens/button_off.png")) self.btexemplo:setfocusimage(nimgl:getimage("imagens/button_on.png")) self.btexemplo:setx(self.x + (self.width - self.btexemplo:getwidth())/2) self.btexemplo:sety(self.y + 45) self.btexemplo:setlabel("botão 1") self.btexemplo:setfocus(true) self.tfentrada = textfield.textfield:new() self.tfentrada:setimage(nimgl:getimage("imagens/textfield_off.png")) self.tfentrada:setfocusimage(nimgl:getimage("imagens/textfield_on.png")) self.tfentrada:setmaxchars(15) self.tfentrada:setx(self.x+(self.width-self.tfentrada:getwidth())/2) self.tfentrada:sety(self.y+100) self.tfentrada:setcontent("ok para editar") function public:paint(g) self.btexemplo:paint(g) self.tfentrada:paint(g) function public:processkeyevent(evt) if evt == "CURSOR_DOWN" then if self.btexemplo:hasfocus() then self.btexemplo:setfocus(false) self.tfentrada:setfocus(true) return true elseif evt == "CURSOR_UP" then if self.tfentrada:hasfocus() then self.btexemplo:setfocus(true) self.tfentrada:setfocus(false) return true No código acima, aproveitamos para implementar uma navegação entre os componentes Button e textfield. No processkeyevent de nossa página utilizamos os métodos :hasfocus() para verificar o estado atual do componente e :setfocus(b) para alterar o modo de foco.

15 Veja que as imagens foco On e Off são alternadas automaticamente durante a navegação com as teclas CURSOR_UP e CURSOR_DOWN do controle remoto. Obs.: No PC estas teclas são simuladas através das teclas direcionais (cima e baixo). Teremos o resultado abaixo: 3.3. VirtualKeyboard Vamos implementar um teclado virtual virtualkeyboard - ao nosso textfield para que possamos permitir ao usuário digitar caracteres alfanuméricos. Adicione esta linha ao main.lua require"virtualkeyboard" Código do arquivo mainpage.lua

16 if PaginaPrincipal then return PaginaPrincipal local public = component.component:new() PaginaPrincipal = public function public:init() self.btexemplo = button.button:new() self.btexemplo:setimage(nimgl:getimage("imagens/button_off.png")) self.btexemplo:setfocusimage(nimgl:getimage("imagens/button_on.png")) self.btexemplo:setx(self.x + (self.width - self.btexemplo:getwidth())/2) self.btexemplo:sety(self.y + 45) self.btexemplo:setlabel("botão 1") self.btexemplo:setfocus(true) self.tfentrada = textfield.textfield:new() self.tfentrada:setimage(nimgl:getimage("imagens/textfield_off.png")) self.tfentrada:setfocusimage(nimgl:getimage("imagens/textfield_on.png")) self.tfentrada:setmaxchars(15) self.tfentrada:setx(self.x+(self.width-self.tfentrada:getwidth())/2) self.tfentrada:sety(self.y+100) self.tfentrada:setcontent("ok para editar") self.vkteclado = virtualkeyboard.virtualkeyboard:new() self.vkteclado:setx(self.x-11) self.vkteclado:sety(self.y+120) self.vkteclado:setmaxletters(15) self.vkteclado:setparent(self) self.vkteclado:init() function public:paint(g) self.btexemplo:paint(g) self.tfentrada:paint(g) if self.vkteclado:isvisible() then self.vkteclado:paint(g) function public:showkeyboard(bol) if bol == false then sticker.sticker:getinstance():releasebuttons() self.vkteclado:setvisible(false) self.tfentrada:setfocus(true)

17 function public:setkeyboardcontent(content) if content ~= "" then self.tfentrada:setcontent(content) else self.tfentrada:setcontent("ok para editar") function public:processkeyevent(evt) if self.vkteclado:isvisible() then return self.vkteclado:processkeyevent(evt) if evt == "CURSOR_DOWN" then if self.btexemplo:hasfocus() then return true elseif evt == "CURSOR_UP" then self.btexemplo:setfocus(false) self.tfentrada:setfocus(true) if self.tfentrada:hasfocus() then return true elseif evt == "ENTER" then self.btexemplo:setfocus(true) self.tfentrada:setfocus(false) if self.tfentrada:hasfocus() then self.tfentrada:stopcaret() sticker.sticker:instance()[1]:requestbuttons() if self.tfentrada:getcontent() ~= "OK para editar" then else self.vkteclado:setcontent(self.tfentrada:getcontent()) self.vkteclado:setcontent("") self.vkteclado:setvisible(true) return true Quando ativamos o botão Concluir do virtualkeyboard, dois métodos da página pai são chamados. O showkeyboard(bol) recebo false e o setkeyboardcontent(content) recebo a string digitada no display do virtualkeyboard. Estes métodos devem ser obrigatoriamente declarados para a correta utilização do virtualkeyboard. Quando iniciamos um virtualkeyboard devemos forçar a parada do textfield, visto que o mesmo possui uma thread em execução que faz com que um

18 cursor dentro do mesmo fique piscando. Fazemos isso no nosso código através da linha self.tfentrada:stopcaret(). Repare que o virtualkeyboard possui seus próprios botões coloridos. Para que o eventos de teclas coloridas sejam propagados para o virtualkeyboard e não sejam tratados pelo sticker, foi necessários executar o comando sticker.sticker:getinstance():requestbuttons(). O tratamento padrão das teclas coloridas foi restabelecido executando a linha sticker.sticker:getinstance():releasebuttons() Exemplo do virtualkeyboard so executado ListMenu O ListMenu é um componente que organiza um conjunto de componentes em abas (Tabs) que podem ser abertas e fechadas pelo usuário. Apenas um conteúdo de uma tab é exibido por vez. Cada separador do ListMenu possui uma imagem para seu estado sem foco e outra para o estado com foco (em azul no exemplo abaixo). Um título para cada tab do ListMenu deve ser definido. A numeração exibida antes do título é adicionada automaticamente pelo componente.

19 O usuário navega entre as abas usando as setas direcionais do controle remoto (para cima e para baixo). Para abrir o conteúdo da aba selecionada (em foco) basta pressionar a tecla OK. Também é possível navegar rapidamente pelo conteúdo das abas pressionando os respectivos números do controle remoto. Por isto, o número limite de abas que podem ser criadas é 9 (correspondente às teclas numéricas do controle remoto; o zero (0) não conta). Veja nas imagens abaixo como cada aba possui seu próprio conteúdo. Vamos à sua implementação. Adicione esta linha ao main.lua require"listmenu"

20 if MainPage then return MainPage local public = component.component:new() MainPage = public function public:init() self.homepage = HomePage:new() self.pagetwo = PageTwo:new() self.pagethree = PageThree:new() self.menu = listmenu.listmenu:new() self.menu:setparent(sticker.sticker:getinstance()) self.menu:setitemimage(nimgl:getimage("../gfx/tab_off.png")) self.menu:setfocusimage(nimgl:getimage("../gfx/tab_on.png")) self.menu:setx(self.x) self.menu:sety(self.y) self.menu:setheight(self.height) self.menu:setwidth(self.width) self.menu:add("tab One", self.homepage, nil) self.menu:add("tab Two", self.pagetwo, nil) self.menu:add("tab Three", self.pagethree, nil) self.homepage:init() function public:paint(g) self.menu:paint(g) function public:processkeyevent(evt) return self.menu:processkeyevent(evt) function public:reset() self.menu:setselected(1) function public:setfocus(boolean) self.menu:setfocus(boolean) function public:notifyfirstinnerfocus() self.menu:notifyfirstinnerfocus()

21 function public:notifylastinnerfocus() self.menu:notifylastinnerfocus() Adicione estas linhas ao arquivo mainpage.lua No código acima criamos um ListMenu (self.menu = listmenu.listmenu:new()) e definimos sua posição x, y (self.menu:setx(self.x) e self.menu:sety(self.y)) e sua altura e largura (self.menu:setheight(self.height) e (self.menu:setwidth(self.width)). À seguir, três tabs são criadas definindo seu título e seu componente de conteúdo respectivamente. self.menu:add("tab One", self.homepage, nil) self.menu:add("tab Two", self.pagetwo, nil) self.menu:add("tab Three", self.pagethree, nil) Obs.: A primeira página do ListMenu deve ser iniciada após ser adicionada. Fizemos isso através da linha self.homepage:init(). Uma boa prática seria chamar o método init() no paint to um controle para não reiniciar os componentes toda vez que for executado o paint do componente. No método paint de nossa MainPage fazemos a pintura do nosso self.menu chamando seu próprio método paint (self.menu:paint(g)). Também é necessário propagar os eventos de tecla para o self.menu no método processkeyevent() de nosso componente MainPage (return self.menu:processkeyevent(evt)) Navegando entre as tabs do ListMenu A navegação entre as tabs é automática quando estas estão fechadas. Porém, quando uma tab está aberta, e navegamos para dentro dela, todos os eventos de tecla passam a ser propagados para o componente visível. Para que o componente possa tratar seu comportamento quando recebe o foco, o ListMenu chamará um dos métodos do componente visível abaixo depo de onde o foco veio.

22 Quando a navegação é proveniente do ListMenu para dentro de uma página visível, o ListMenu irá invocar os métodos do componente conforme ilustrado abaixo. function HomePage:notifyFirstInnerFocus() self.textfield1:setfocus(true) self.textfield1 self.button function HomePage:notifyLastInnerFocus() self.button:setfocus(true) Uma vez o foco estando dentro do componente, todos os eventos serão tratados pelo mesmo, e não mais pelo ListMenu. Vejamos então como devolver o foco para o ListMenu. Ainda no nosso exemplo, supondo que o botão Ok esteja focado e o usuário pressione a tecla CURSOR_DOWN.

23 Neste caso, o foco deverá sair do componente e ir para a Tab Two do nosso ListMenu. Dentro do código do nosso componente ativo (HomePage), devemos então chamar o método notifynext() do ListMenu. Como o ListMenu é o pai de nosso componente, este será chamado como self:getparent():notifynext(). Veja como implementamos isto em nossa HomePage: function public:processkeyevent(evt) if evt == "CURSOR_DOWN" then if self.button:hasfocus() == true then self.button:setfocus(false) self:getparent():notifynext() return true self.button self:getparent():notifynext()

24 Se estivéssemos subindo o foco com o CURSOR_UP do componente para o ListMenu, teríamos que chamar o método self:getparent():notifyprevious(). Veja o exemplo abaixo. function public:processkeyevent(evt) if evt == "CURSOR_UP" then if self.textfield1:hasfocus() == true then self.textfield1:setfocus(false) self:getparent():notifyprevious() return true self:getparent():notifyprevious() self.textfield1

25 4. Subindo o Sticker para o Portal do Desenvolvedor Antes de enviarmos um Sticker para o portal do desenvolvedor, precisaremos ter algumas imagens preparadas, que são usadas na StickerShop e no Portal StickerCenter. As imagens devem obdecer os seguintes padrões de nomenclatura, formato e dimensão: Imagem Nome do arquivo Tamanho exibition.png 66 x 55 pixels ico.png 96 x 84 pixels screenshot.png 114 x 269 pixels

26 Para subir um Sticker para o Portal do Desenvolvedor, ele deverá ter a estrutura abaixo: A pasta source conterá todo o código e imagens utilizadas pelo Sticker. Todos estes arquivos deverão ser compactados em um único arquivo.zip, que deve ser enviado via formulário no Portal do Desenvolvedor.

27