# 8.4. Editar um Projecto

Após ter criado um projecto novo com o KAppWizard, a tarefa habitual é ampliar o projecto editando o código já criado e adicionar classes, pixmaps, imagens e o que mais o seu projecto necessitar. Agora, editar um projecto significa que você pode modificar o projecto de defeito após a sua geração através de menus e diálogos de acordo com as suas necessidades. A secção seguinte descreve assim como pode adicionar ficheiros existentes e classes bem como criar novos ficheiros. Isto é necessário para construir o seu projecto, mas não o ajudará no processo de instalação para o utilizador final. Desta forma, a secção Definir Opções de Ficheiros do Projecto descreve como definir Propriedades dos Ficheiros especialmente para adicionar ficheiros que deseja que o make instale, tais como documentação ou pixmaps. Outra parte na manutenção de um projecto é adicionar traduções para a aplicações que suportem internacionalização, o que é descrito em Adicionar Traduções.

Extender a Documentação do Projecto cobre questões sobre como criar um bom conjunto de documentação para ajuda electrónica permitindo ao utilizador final ajudar-se a si próprio em caso de problemas bem como saber utilizar o seu produto.

Finalmente, Hacking do Projecto descreve como poderá eventualmente trabalhar à volta da gestão do projecto no KDevelop em casos especiais.

## 8.4.1. Adicionar e Remover Ficheiros e Classes

Adicionar um novo ficheiro é muito utilizado quando pensa em separar o seu ficheiro de implementação de classes em vários. Depois você necessita de criar um novo ficheiro que contenha parte da implementação da classe que deseja mover. Pode fazer isto escolhendo "Novo" a partir do menu "Ficheiro", abrindo o diálogo "Novo Ficheiro". Isto permite-lhe especificar o tipo de ficheiro, nome e localização. Depois de inserir o nome do ficheiro, o KDevelop automaticamente acrescenta a extenção por si, mas pode modificar a extenção segundo as suas preferências. Mais ainda, pode incluir o modelo de cabeçalho para ficheiros de código, pelo que não tem de copiar isto para o seu novo ficheiro manualmente. Também, você pode decidir, de o ficheiro é ou não incluido no projecto. Lembre-se que isto não cobre o destino de instalação; isto tem de ser configurado mais tarde definindo as preferências de ficheiro.

Depois de o novo ficheiro ter sido criado, o ficheiro de projecto será actualizado bem como os correspondentes Makefile.am's. Para adicionar uma classe completa ao seu projecto, pode construir uma nova classe no Gerador de Classes que é invocado pela entrada "Nova Classe" no menu Projecto.

No caso de ter um projecto existente e querer adicionar certas classes que deseja re-utilizar no seu projecto, seleccione "Adicionar Ficheiros(s) ao Projecto..." a partir do menu Projecto. Seleccione "Adicionar ficheiros existentes", que irá abrir um diálogo para lhe permitir especificar que ficheiros serão adicionados ao projecto e o directório de destino. Lembre-se que os ficheiros serão copiados para o directório especificado e adicionados ao projecto. Deverá chamar o "Make" após adicionar código; depois os ficheiros por si adicionados serão incluidos no processo de construção. No caso de querer adicionar por ex. pixmaps que têm de ser instalados pelo utilizador final, deverá actualizar as Propriedades do Ficheiro para o ficheiro adicionado e especificar o caminho de instalação (veja Definir Opções de Ficheiros do Projecto

Para adicionar um ficheiro ao projecto que já se encontra no directório do projecto, vá ao VFR, onde todos os ficheiros incluídos no projecto são apresentados pelo seu estado no projecto através de um ! a vermelho sobre o icon do ficheiro. Seleccione o ficheiro que deseja adicionar ao projecto (que tem um icon de ficheiro normal) e prima o botão direito do rato para obter o menu de contexto. Depois seleccione "Adicionar".

Ficheiros podem também ser removidos do seu projecto. Isto pode ser necessário em casos em que não deseja utilizar ficheiros pré-gerados que são já dados pelo KAppWizard. Para remover um ficheiro, tem adicionalmente a opção entre remover o ficheiro do projecto ou apaga-lo completamente. Para remover um ficheiro do projecto, seleccione o ficheiro no VFL ou no VFR, pressione o botão direito do rato e seleccione "remover". Para apagar um ficheiro, seleccione "apagar fisicamente".

## 8.4.2. Definir Opções de Ficheiro de Projecto

O diálogo de propriedades do ficheiro pode ser acedido através do menu projecto ou dentro do VFL através de um clique do botão direito do rato. Mostra os ficheiros do projecto em grupos como estão ordenados no VFL e são apresentadas as propriedades dos ficheiros tais como tamanho do ficheiro, tipo de ficheiro e se o ficheiro está incluido no projecto bem como o caminho de instalação se o ficheiro for ser instalado pelo comando make install do utilizador final. É importante para ficheiros de documentação bem como pixmaps especificar a licalização para onde os ficheiros devem ir quando o projecto é construido e instalado pelos utilizadores finais, pelo que tem de definir estas localizações. Para macros de localizações standard KDE deverá procurar no seu Makefile.am onde as macros de localização são especificadas.

## 8.4.3. Adicionar Traduções

Como o KDE permite configurar o seu ambiente de trabalho e o comportamento das suas aplicações, tem também a opção de escolher o idioma que a sua aplicação utiliza, no que toca à utilização de documentação electrónica bem como do aspecto da aplicação. Para ficheiros de documentação, isto parece uma tarefa trivial. Deverá adicionar um subdirectório com o nome do idioma desejado, por ex. `de` para alemão, ao directório `docs` do seu projecto e copiar a documentação em inglês para esse directório. Depois deverá gerar a documentação e definir todas as opções de ficheiros de projecto para os directórios de instalação. Depois poderá começar a traduzir o ficheiro sgml para o seu idioma desejado e re-gerar a documentação; ficará tudo pronto. Para a aplicação, isto é um pouco mais difícil para o programador. Agora, nós queremos explicar como permitir suporte para internacionalização na sua aplicação e como adicionar idiomas que deseje suportar.

Primeiro, tem de delimitar todo o texto visível da sua aplicação que surge em barras ou diálogos com a macro `i18n()`. Esta macro é a substituição para a função `klocale->tranlate()` da classe KLocale e muito mais fácil de utilizar. Como esta macro é declarada no ficheiro include `kapp.h`, tem de adicionar `#include <kapp.h>` ao ficheiro de código ou ficheiro de declaração de classe da classe que faz uso desta macro. Também deverá ser mencionado, que apesar de `i18n()` ser uma macro e por isso você poderia pensar em utilizar a função original, mas isto não irá funcionar porque os textos que são definidos para tradução têm de ser lidos a partir do código e serem guardados no ficheiro de tradução da aplicação (<SuaApl>.pot no subdirectório /po ). Esta tarefa é feita pelo programa xgettext, e para o fazer, você deverá escrever `make messages` no directório do seu projecto contendo o código. Como o xgettext depende da macro `i18n()`, a função original não conseguirá realizar a tarefa.

Para as traduções em si, tem primeiro de criar o ficheiro de mensagens contendo todos os textos a serem utilizados no seu código com a macro `i18n()`. isto pode ser feito escolhendo "Make Messages e juntar" a partir do menu Construir. Depois tem de adicionar os idiomas que a sua aplicação deseja suportar. Para tal, seleccione "Adicionar Ficheiro de Tradução" a partir do menu Projecto. Isto abre o diálogo de selecção de idioma. Seleccione o idioma e prima OK. Isto irá construir o ficheiro ASCII contendo entradas para o ficheiro do texto e a linha onde o texto original é colocado. Depois irá ver uma linha `msgid` contendo o texto a ser traduzido, seguido de `msgstr`. A linha msgstr é normalmente vazia excepto para as traduções já disponibilizadas pelas bibliotecas KDE . Essas têm de ser preenchidas com as traduções correspondentes para o seu idioma.

Poderia pensar em escrever as traduções manualmente, o que pode ser feito. Mas o KDE-SDK disponibiliza a utilização do programa KTranslator, que abre os ficheiros existentes de outras aplicações instaladas no sistema, para que possa re-utilizar textos já traduzidos para suportar o seu idioma.

Para aceder ao KTranslator, a forma mais fácil é seleccionar um ficheiro <idioma>.po no directório /po quer através do VFL ou no VFR. Isto abre o KTranslator permite-lhe fazer a tradução facilmente. Lembre-se que tem de definir você mesmo as propriedades do KTranslator para incluir o nome do autor e o idioma bem como o ficheiro de destino. O KTranslator por defeito apenas abre o seu ficheiro de tradução.

Para todos os ficheiros de tradução, `make` utiliza o programa `msgfmt` para formatar os seus ficheiros de mensagens para utilizar com o binário, mas você não tem de tomar conta disto, bem como especificar o directório de destino para instalar os ficheiros de tradução; isto é tudo feito automaticamente pelo KDevelop.

Para mais informações sobre suporte à internacionalização, veja http://www.kde.org; imensas pessoas estão a fazer traduções para si para suportar o idioma deles. Irá encontrar uma lista de endereços e-mail dos tradutores a que poderá escrever e que o ajudarão com isto. Leia também O Editor de Diálogos e O Manual de Programação do KDevelop onde questões sobre a internacionalização são de novo abordadas.

## 8.4.4. Aumentar a Documentação do Projecto

Todos os projectos criados com o KDevelop contêm uma documentação pré-configurada, que já contém capítulos standard para instalação, nome de projecto e versão bem como o nome do autor e endereço email. Como o KDevelop utiliza modelos SGML, é muito simples ampliar a documentação para um sistema de ajuda completamente descritivo. A única coisa que tem de fazer é editar o ficheiro sgml, colocado em docs/en como index.sgml. A documentação de referência incluida com o seu pacote de ferramentas sgml pode ser adicionada ao navegador de ajuda e permitir-lhe acesso directo a algumas tags especiais bem como uma breve descrição de como expandir a sua documentação. O SGML tem imensas vantagens, pelo que o KDE faz grande uso deste tipo de documentação adicionalmente à ferramenta ksgml2html. Isto cria a documentação tipica estilo-KDE e fa-la ter um melhor aspecto. De qualquer forma, as ferramentas sgml por si são o suficiente para produzir um resultado em html que é logo incluido na sua aplicação. Para criar os documentos utilizando o ksgml2html, instale a ferramenta e corra "Make Manual do Utilizador" a partir do menu Construir. O Navegador de Documentação permite um controlo directo do resultado seleccionando "Manual do Utilizador do Projecto" a partir do menu Ajuda ou do icon correspondente na árvore DOC. Pode depois navegar a sua documentação electrónica no KDevelop e ter uma melhor visão do resultado final em relação a erros resultantes de tags que não foram escritas.

Agora, enquanto a ampliar a documentação, não pode evitar que ficheiros adicionais sejam produzidos e tenham de ser incluidos no projecto já que cada `sect`-tag cria um novo ficheiro HTML. O resultado final gerado pelo KAppWizard já se encontra incluido no projecto, pelo que não se tem de preocupar com o seu caminho de instalação. O que tem de observar é qualquer ficheiro index-xx.html, onde xx é superior a 6 (já que as primeiras seis páginas já estão incluidas no projecto). Após gerar a documentação, mude para o VFR e vá para o seu directório de documentação. Prima o botão direito do rato sobre os ficheiros a adicionar e seleccione "Adicionar". Além disso, o ksgml2html adiciona o logotipo KDE ao directório da documentação. Este ficheiro, `logotp3.gif`, tem também de ser adicionado ao projecto. Depois tem de seleccionar "Propriedades de Ficheiros" quer a partir do menu Projecto ou pelo menu de contexto nos visualizadores de ficheiros. A forma mais fácil de definir o caminho de instalação é seleccionar um ficheiro de documentação já definido para instalação tal como o `index.html`. Verá que o `Instalar` está activo e o Directório de Instalação+Nome de Ficheiro já contêm o destino. Marque o Directório de Instalação prima CTRL+C para copiar o caminho de instalação para a área de transferência. Depois seleccione o ficheiro que deseja especificar para instalação. Active `Instalar`, o que irá activar o campo Directório de Instalação, já contendo o nome do ficheiro. Coloque o cursor em frente do nome do ficheiro e prima CTRL+V para inserir o conteudo da área de transferência (que eram o caminho de instalação copiado anteriormente). Esta é a forma mais rápida de especificar o caminho de instalação. Para mais opções sobre especificação de destinos de instalação, veja O Manual de Programação do KDevelop.

## 8.4.5. Hacking ao Projecto

Quando a trabalhar com um projecto, nunca deverá editar o ficheiro do projecto manualmente. Isto impedirá o KDevelop de ler o seu projecto correctamente em algumas circunstâncias, bem como alterações não irão resultar na actualização dos ficheiros Makefiles. Para modificar quaisquer definições para o seu projecto, tem de utilizar as entradas de menu existentes tal como por ex. para adicionar ficheiros ou definir propriedades de ficheiros. Para grandes conehcedores que não estão à vontade com certas opções por ex. o linkador ou configurações adicionais de projecto necessárias, deverá mexer por si nas macros dos Makefile.am e adicionar todas as modificações nos Makefile.am's após a secção separada com a entrada "KDevelop write area". Como as ferramentas GNU estão a utilizar os comandos no final de todos os ficheiros macros, pode passar por cima das definições do KDevelop desta forma. Lembre-se que isto o impedirá de utilizar o KDevelop para quaisquer modificações relacionadas com a configuração do projecto.