SCV Canvas2d Manual do Programador

Transcrição

1 SCV Canvas2d Manual do Programador O SCV é uma API (Application Programming Interface) de facilitação na construção de interfaces de usuário (GUI Graphic User Interface), orientada ao uso de um programador com experiência na linguagem de programação C++. Foi desenvolvido sobre a API Canvas2D, e atualmente na versão beta, tem a distribuição com funcionamento garantido apenas na plataforma Windows. Este guia tem o propósito de orientar o programador no aprendizado da utilização do SCV. A primeira parte é destinada às explicações sobre o processo de instalação, necessária antes de sua utilização semelhante ao modo como é necessário preparar a estação de trabalho antes de utilizar as bibliotecas OpenGL. Posteriormente, são dadas especificações sobre as ferramentas oferecidas pela API, os components e peripherals; e por fim sobre a utilização de ColorSchemes. Importante: esta distribuição do SCV é de uma versão beta, para utilização na disciplina de Computação Gráfica. Uma nova versão será produzida posteriormente, focando-se em oferecer uma distribuição multi-plataforma. Não será garantida a retro-compatibilidade da nova versão com os programas desenvolvidos na versão beta. Instalação Este manual oferece um guia de instalação para as IDE s (Integrated Development Environment) Visual Studio e Dev-C++. Acesse a página do Professor Cesar Pozzer ( onde você encontrará as bibliotecas necessárias para a utilização do SCV. Primeiro, instale o OpenGL conforme as instruções do arquivo compilar_opengl.pdf, também disponível na mesma página no link Demos, na página dedicada ao conteúdo da disciplina Computação Gráfica 3D. Depois disso, tendo adquirido o arquivo SCV_lib_for_Windows.rar, descompacte-o. Siga os seguintes passos, dependendo da sua IDE. Visual Studio 8: Copie o arquivo SCV.h que está na pasta SCVLIB\VisualStudio8\VC\include, do arquivo que você descompactou. Cole-o na pasta correta: Microsoft Visual Studio 8\VC\include. Copie o arquivo SCV.lib que está na pasta SCVLIB\VisualStudio8\VC\lib do arquivo que você descompactou. Cole-o na pasta Microsoft Visual Studio 8\VC\lib. Os passos acima só precisam ser executados uma vez. Os passos abaixo devem ser executados toda vez que for criado um novo projeto alternativamente, você pode utilizar o arquivo de projeto fornecido como demo na documentação do SCV.

2 Após criar um novo projeto, pressione ALT+F7 ou vá a Project>NomeDoProjeto Properties..., como indicado na figura Exemplo 1 de instalação Visual Studio, abaixo: Figura: Exemplo 1 de instalação Visual Studio Sob o item Configuration Properties > C/C++ > Code Generation, no item "Runtime Library", clique na caixa que contém a RTL atual e selecione "Multi-threaded Debug DLL (/MDd)", conforme indicado na figura Exemplo 2 de instalação Visual Studio. Pressione OK. Figura: Exemplo 2 de instalação Visual Studio.

3 DevCpp: Copie o arquivo SCV.h que está na pasta SCVLIB\DevC++\include do arquivo que você descompactou. Cole-o na pasta correta: Dev-Cpp\include. Copie o arquivo SCV.lib que está na pasta SCVLIB\DevC++\lib do arquivo que você descompactou. Cole-o na pasta Dev-Cpp\lib. Os passos acima devem ser realizados apenas uma vez para cada estação de trabalho. Os passos abaixo devem ser repetidos toda vez que for criado um projeto. Executando o Dev-C++, após criar um projeto, vá em Project>Project Options, conforme a figura Exemplo 1 de instalação Dev-C++. Figura: Exemplo 1 de instalação Dev-C++. Na janela que abre, sob a aba Parameters, insira a seguinte linha na caixa Linker, conforme a figura Exemplo 2 instalação Dev-C++: -lscv -lopengl32 -lglut32 -lglu32 lwinmm Dê OK. Figura: Exemplo 2 instalação Dev-C++.

4 Ferramentas do SCV O SCV, assim como o Canvas2D, tem a propriedade de oferecer ao programador um tratamento mais fácil e direto das entradas de mouse e teclado através de callbacks. As callbacks de mouse e teclado então têm o funcionamento dirigido pelo programador que utiliza a API na construção de seu programa. Também é utilizada uma função callback de components, para possibilitar ao programador o tratamento da interação do usuário com sua interface do modo que for apropriado ao programa. A estruturação de GUI s no SCV é baseada em dois conceitos principais: periféricos (peripherals) e componentes (components). Components são todos os itens que oferecem uma interação do usuário final com o programa e/ou expressam informação através de sua interface gráfica como, por exemplo, os buttons (botões) e as Labels (texto de interface). Peripherals são as definições de áreas, as separações, onde componentes específicos podem ser inseridos.

5 Peripherals A figura abaixo exemplifica os conceitos de componentes e periféricos de modo mais claro. Figura 1: Exemplo de interface gerada pelo SCV, com indicações dos componentes em numeração em vermelho e dos periféricos e do Canvas (a área de desenho) em azul. Os componentes mostrados são: 1- ActionButton, 2- Switch, 3- SlideBar, 4- TextField. Ainda como componentes nessa figura há uma Label no periférico TopBar e MenuItems na MenuBar. A interface mostrada na figura inclui todos os peripherals possibilitados pelo SCV. Todos são optativos, sendo possíveis todos os tipos de combinações entre eles. São:

6 MenuBar: uma barra destinada à inserção de MenuItems, com a posição fixa no topo da tela. O propósito deste periférico é oferecer uma disposição semelhante à organização de interfaces já consagradas, possibilitando a concentração das funções essenciais de um programa em menus e submenus (que abrem expandindo-se a partir de um item de menu original). A figura 2 exemplifica um submenu em exposição. A MenuBar não pode incluir components que não sejam MenuItems. Figura 2: uma lista de submenus abertos. Os submenus são MenuItems inseridos a partir do item de menu (também um MenuItem) que fica na MenuBar. Mais sobre os MenuItems na seção sobre componentes. TopBar: um periférico optativo que posiciona-se abaixo da MenuBar, quando esta existe, ou no topo da tela, em caso contrário. Tem altura variável e se estende lateralmente de um lado ao outro da tela destinada ao programa. Pode incluir qualquer component que não seja um MenuItem. LeftBar e RightBar: separações laterais que tem a base sobre a StatusBar, quando esta existe, e na base da tela destinada ao programa quando não existe. A parte superior dos peripherals LeftBar e RightBar ligam-se à TopBar. Quando esta não existe, ligam-se à MenuBar e se esta também não existir, ao topo da janela do programa. Os peripherals de barras laterais LeftBar e RightBar existem independemente um do outro pode-se utilizar apenas a LeftBar, por exemplo. Estes peripherals podem incluir qualquer componente que não seja um MenuItem. StatusBar: um peripheral destinado à exposição de informação. Sempre liga-se à parte mais inferior da janela destinada ao programa quando existe. Nesta versão beta do SCV, o único componente que uma StatusBar pode incluir são Labels. Está em desenvolvimento outro componente exclusivo da StatusBar: Separators.

7 Components Os components são : MenuItem: são components que podem ser adicionados exclusivamente à MenuBar ou como filhos de outro MenuItem. Não é possível adicionar mais que um nível de submenus, ou seja, um MenuItem só pode ser adicionado como filho de um MenuItem que foi adicionado à MenuBar. Cada MenuItem tem uma ação associada a ele: os MenuItem que são pais, adicionados à MenuBar, possuem a ação única de abrir uma lista de submenus. Os demais tem a ação definida pelo programador que utiliza o SCV. ActionButton: um botão normal de ação, que realiza uma ação quando clicado pelo mouse. A ação é definida pelo programador que utiliza o SCV. Switch: semelhante a um botão, o Switch possui dois estados distintos, como um interruptor de tomada. Ele pode estar pressionado e solto. As ações para cada estado são definidas pelo programador que utiliza o SCV. SlideBar: uma barra de rolagem que tem um marcador deslocado pelo mouse. Os valores mínimo e máximo são definidos pelo programador. O programador é fornecido de um método para interpretar o valor indicado pela SlideBar. Label: uma simples etiqueta, que imprime uma string na interface do SCV. TextField: uma caixa de texto editável pelo usuário do programa. O programador é fornecido de um método para requisitar o texto que a TextField contém em formato de string. Mais components serão desenvolvidos para versões futuras do SCV. Entre os components já em desenvolvimento estão: Tooltips, Separators, CheckBox, RadioButton, ScrollBar, e Tab. Se você tem alguma sugestão, encaminhe-a aos autores do SCV ou ao Professor Cesar Pozzer para que seja estudada a implementação.

8 Colorschemes Um ColorScheme é um padrão de cores a ser aplicado à interface gerada pelo SCV. Pode ser gerenciada pelo programador, e modificada no decorrer do programa. Todos os components e peripherals baseiam-se no ColorScheme vigente para desenhar-se cabe ao programador gerenciar os demais ColorSchemes com estruturas de dados próprias. Um ColorScheme contém as seguintes cores: Fill color: a cor de preenchimento; Light Fill color; a cor de preenchimento mais clara; Border color; a cor das bordas e linhas de separação; Dark fill color; a cor de preenchimento mais escura, também usada para texto em vários components; Shadow color; a cor das sombras e detalhes em gradiente; Menu color; a cor da lista de submenus e alguns itens; Detail color; a cor de detalhes da interface. Segue abaixo um exemplo de uso de ColorSchemes, com o programador utilizando um vector de ColorScheme para gerenciamento: 1. vector <ColorScheme*> storage; 2. ColorScheme* novocs = new ColorScheme(); 3. novocs->setmenucolor(142,100,10,255); 4. novocs->setlightfillcolor(105,205,255,255); 5. novocs->setfillcolor(255,255,255,255); 6. novocs->setdarkfillcolor(100,255,255,255); 7. novocs->setbordercolor(100,255,0,255); 8. novocs->setshadowcolor(0,0,0,255); 9. novocs->sethighlightcolor(255,255,255,255); 10. novocs->setdetailcolor(255,255,255,255); 11. storage.push_back(novocs); 12. ColorScheme::applyColorScheme(storage[0]); Neste exemplo, na linha 1 o programador utiliza um vector para guardar os ColorSchemes que sua aplicação utilizará. O SCV já vem com um esquema de cores padrão, e a simples criação (instanciação) de outros não é suficiente. O programador declara um novo ColorScheme, no exemplo na linha 2, e tem então de setar as cores separadamente pelos valores (em ordem, como parâmetros em todas as funções expressas nas linhas 3 até 10): vermelho, verde, azul e transparência (alpha, padrão RGBA).

9 Cores não setadas pelo programador assumem um valor arbitrário. Note que as cores de um ColorScheme são aplicadas somente quando é chamado applycolorscheme(colorscheme* newcs), onde newcs é um ponteiro para o ColorScheme que se quer aplicar. Para referência, o ColorScheme padrão do SCV é: ColorScheme padrão do SCV COR R G B A FILL LIGHT FILL DARK FILL SHADOW MENU HIGHLIGHT DETAIL Cada componente da cor tem valores entre 0 e 255 Tenha em mente que não são todas as combinações de cor que resultam em interfaces agradáveis. É preferível escolher cores que combinem, com algumas conflitantes para pontos em destaque. Uma boa fonte é o site: que gera cores correlatas à uma inserida pelo usuário.

10 Exemplos: Exemplo de uso básico do SCV: Primeiro, execute os passos de instalação. No código do programa, inclua o arquivo SCV.h #include <SCV.h> Agora é necessário inicializar o SCV, semelhante à maneira como se inicializava o antigo Canvas2d. A função para tal é initscv para utilizá-la, é necessário especificar o namespace SCV, passando os parâmetros necessários. Exemplo: SCV::initSCV(400,400,mouse,keyboard,component,render); No exemplo, que pode ser adquirido na página do Professor Cesar Tadeu Pozzer, as callbacks já estão criadas e definidas com os nomes vistos no exemplo acima: mouse, keyboard, component e render. Você pode, no entanto, criar as próprias funções de callback, passando-as como parâmetro na função de inicialização do SCV. Estas funções irão tratar, respectivamente das entradas do mouse, das entradas de teclado, dos chamadas dos componentes e renderização do programa. O método SCV::about é opcional, mostrando informações sobre o SCV quando da execução do programa. Como o Canvas2d, o SCV possui uma repetição ininterrupta (loop) do código de renderização, que deve ser iniciado pela função runscv, também do namespace SCV. SCV::runSCV(); Todos os peripherals e os components contidos neles devem ser criados no código entre as funções initscv e runscv. Um exemplo segue: 1. SCV::initSCV(400,400,mouse,keyboard,component,render); 2. SCV::setMenuBar(); 3. MenuItem *arqui = new MenuItem(0, "Arquivo"); 4. MenuItem *novo = new MenuItem(1, "Novo"); 5. MenuItem *load = new MenuItem(2, "Carregar"); 6. MenuItem *sair = new MenuItem(3, "Sair"); 7. arqui->additem(novo); 8. arqui->additem(load); 9. arqui->additem(sair); 10. SCV::addToPeripheral(MENU_BAR,arqui); 11. SCV::runSCV(); No exemplo acima é fácil distinguir que entre os métodos initscv e runscv foram criadas uma MenuBar, na linha 2, através do método setmenubar e, após isto, um item de menu Arquivo que

11 tem como filhos Novo, Carregar e Sair, outros três menuitens, é adicionado à barra de menus (através da função addtoperipheral. O menu criado aqui é aquele da figura 2. Note que o processo de criação de components e peripherals deve seguir esta ordem: acionar o peripheral através do método correspondente (setmenubar, settopbar, etc); instanciar o componente (como na linha 3 do exemplo acima); adicionar o component ao peripheral desejado. No exemplo acima, como o component adicionado era um MenuItem, ele teve de ser obrigatoriamente adicionado ao peripheral StatusBar. Este peripheral adiciona os componentes da esquerda para a direita, estaticamente. Na instanciação dos demais components, via de regra, é necessário fornecer a posição do componente (coordenadas x, y) em relação ao peripheral ao qual será adicionado. O ponto de origem de todos os peripherals e components no SCV é o ponto inferior esquerdo. Exemplo de gerenciamento de callbacks de components Digamos que o programador incluiu em sua interface um TextField e quer que, assim que a entrada seja pozzer, seja executado o código de uma função ou método específico, no nosso exemplo chamado de callpozzer(). Vamos mostrar três exemplos, assumindo que a callback de components foi definida como component. Primeiro, digamos que é necessário que callpozzer() seja executado somente se o usuário inserir pozzer em um TextField específico e confirmar a entrada com enter. SCV::TextField* textfield = new SCV::TextField(&TextFieldTeste,100,10,68); SCV::addToPeripheral(TOP_BAR,textField); Note que TextFieldTeste é um inteiro (nesse caso, proveniente de um enum aconselha-se utilizar enum para gerenciamento dos id s de components) que é o número de identificação do component. Agora, com o TextField já instanciado, você pode usar a callback de component que é chamada para executar a ação determinada de todos os componentes. Por exemplo, quando o usuário clica num ActionButton, quando o usuário entra uma informação no TextField selecionado, etc. void component(int id, SCV::UserComponent* comp, int type) { if(id == TextFieldTeste) { if(((scv::textfield*)(comp))->gettext() == "Pozzer") callpozzer(); } }

12 A identificação de qual component chamou a callback é feita no código da própria callback, como no exemplo acima. É importante lembrar que é necessária uma cast do SCV::UserComponent recebido como parâmetro (i.e, o component que chamou a callback) para o tipo adequado a ser tratado. Por padrão, o TextField só chama a callback de components quando o usuário tecla enter. Isso pode ser mudado através do método setcalleachkey do próprio TextField. Assim, a cada vez que o usuário pressionar uma tecla com o TextField em foco, a callback será chamada.

13 Créditos, contato, sugestões e bug report. O SCV foi criado sob orientação do Professor Dr. Cesar Tadeu Pozzer, do Grupo de Tecnologia Gráfica (ggraf) do Laboratório de Computação Aplicada (LaCA) da Universidade Federal de Santa Maria UFSM. Os acadêmicos envolvidos no projeto foram: Bernardo Henz, Celito Muck Felipetto, Eduardo Arrial Speroni e Vinícius Michel Gottin; acadêmicos do curso de Ciência da Computação da UFSM. Caso sejam encontradas dificuldades no uso do SCV, ou você tenha sugestões, críticas ou comentários sobre o SCV entre em contato com os desenvolvedores através de qualquer um dos s: {henz, felipeto, eduardos, Alternativamente, você pode entrar em contato com o Professor Pozzer através do pozzer@inf.ufsm.br. Mais informações, download de novas versões e documentação do SCV podem ser encontradas na página Agradecemos o feedback com antecedência, Equipe desenvolvedora do SCV.