<chapter id="getting-started">

<!-- ToDo: 
Put the AppWizard section at the beginning.
Before anything else, let the user generate
a hello program like this:
- assumes KDevelop is properly installed,
  e.g. from a good Linux distribution
  (list those that include KDevelop?)
- start KDevelop
- if settings are needed, accept default ones
- Project - New Project
- C++ - KDE - Simple KDE application
- name: hello, location: default (/home/user). Next
- Project Options: Leave as default. Next
- .h Template: Leave as default. Next
- .cpp Template: Leave as default. Finish
- Build - Execute Program (Yes to run automake & friends)
- Messages window appears. Wait until program is compiled.
- Finally, program pops up, saying "Hello World".

After this, explore the KDevelop functionality
with the hello program as an example.

Also: Links to detailed descriptions in the main part.
Volker Paul
-->

<chapterinfo>
  <authorgroup>
    <author
><firstname
>Bernd</firstname
><surname
>Pol</surname
></author>
    <!-- ROLES_OF_TRANSLATORS -->
  </authorgroup>
</chapterinfo>

<title
>Introdução ao &kdevelop; &mdash; Uma Visita Guiada</title>

<para
>Agora que você instalou o seu IDE &kdevelop;, como é que o vai utilizar bem? Dado que esta é uma aplicação complexa, a curva de aprendizagem pode ser um pouco inclinada, principalmente se não estiver já habituado a este tipo de ambientes de desenvolvimento integrados. </para>
<para
>Iremos tentar suavizar esta curva de aprendizagem um pouco, vendo os passos de criação de uma aplicação do KDE em C++. Como tal, iremos dar uma vista de olhos (focada) em: </para>
<simplelist>
  <member
><link linkend="gettingstarted-overview"
>O que é visto à superfície do IDE do &kdevelop;.</link
></member>
<!--  <member
><link linkend="gettingstarted-configure"
>Some initial configuration steps.</link
></member
> -->
  <member
><link linkend="gettingstarted-new"
>Como criar um novo projecto.</link
></member>
<!--  
  <member
><link linkend="gettingstarted-edit"
>How to work with documents.</link
></member>
  <member
><link linkend="gettingstarted-compile"
>How to compile the application in this project.</link
></member>
  <member
><link linkend="gettingstarted-extend"
>How to add classes and other detail to your project.</link
></member>
  <member
><link linkend="gettingstarted-debug"
>What to do to debug the application.</link
></member>
  <member
><link linkend="gettingstarted-doc"
>Some basic tools to build program or user documentation.</link
></member>
-->
</simplelist>

<sect1 id="gettingstarted-overview">
<title
>Uma Vista Introdutória sobre o &kdevelop;</title>

<sect2 id="gettingstarted-overview-basic">
<title
>À Superfície</title>

<para
>Quando você inicia o &kdevelop; pela primeira vez, irá obter uma visualização semelhante à seguinte: </para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="empty-ide.png" format="PNG"/>
    </imageobject>
    <caption
><para
>A disposição inicial do &kdevelop; </para
></caption>
  </mediaobject>
</screenshot>

<formalpara>
<title
>Área de Trabalho e Páginas das Janelas de Ferramentas</title>
<para
>Neste caso inicial, o &kdevelop; usa o modo denominado por <link linkend="uimodes-survey"
>modo de interface de utilizador IDEAl</link
>. Um espaço de trabalho com o tamanho máximo possível fica rodeado pela esquerda, baixo e direita por uma série de botões que actuam de forma semelhante às páginas numa área dividida em páginas. Se carregar numa destas páginas, aparece então uma <emphasis
>janela de ferramentas</emphasis
> que lhe permitirá trabalhar numa tarefa específica. </para>
</formalpara>

<formalpara>
<title
>Menu e Barras de Ferramentas</title>
<para
>No topo, existe o menu normal, seguido de várias filas de barras de ferramentas, estando algumas vazias inicialmente. Elas serão preenchidas, logo que exista um projecto aberto para o trabalho de facto. </para>
</formalpara>

<formalpara>
<title
>Barra de Estado</title>
<para
>Finalmente, existe uma barra de estado no fundo da janela que mostra algumas informações curtas sobre as várias tarefas. </para>
</formalpara>
</sect2
> <!-- gettingstarted-overview-basic -->

<sect2 id="gettingstarted-overview-help">
<title
>Como Obter Alguma Ajuda</title>

<para
>Para além da <guimenu
>Ajuda</guimenu
>, que oferece algumas respostas a perguntas específicas, a barra de estado e dois tipos de dicas de ferramentas oferecem algumas informações rápidas. </para>

<formalpara>
<title
>O Que Este Item do Menu Faz?</title>
<para
>Quando você coloca o cursor do rato sobre um item do menu, existe alguma informação curta que será apresentada na barra de estado. Embora isto, em alguns casos, repita apenas o nome da selecção, noutros poderá oferecer algumas informações adicionais sobre o intuito do comando do menu.</para>
</formalpara>

<formalpara>
<title
>Qual é o Nome Deste Item?</title>
<para
>Em vários itens, irá aparecer uma dica com um nome curto da função, quando você colocar o cursor por cima dela durante alguns segundos. Isto é útil para uma orientação rápida na barra de ferramentas ou nas páginas de ferramentas no modo IDEAl, quando o IDE tiver sido configurado para mostrar os ícones apenas nestes botões.</para>
</formalpara>

<formalpara>
<title
>O Que é Que Este Item Faz?</title>
<para
>Está disponível mais alguma informação, através da ajuda de dicas de ferramentas para muitos itens do IDE. Seleccione a opção <menuchoice
><guimenu
>Ajuda</guimenu
> <guimenuitem
>O Que É Isto?</guimenuitem
></menuchoice
> ou carregue em <keycombo
><keycap
>&Shift;</keycap
><keycap
>F1</keycap
></keycombo
>, podendo então com o cursor do ponto de interrogação seleccionar o item que deseja conhecer. Poderá também abrir qualquer menu desta forma e carregar num item específico do menu (tanto os activos como os desactivados, a cinzento) para ver se está disponível mais alguma informação.</para>
</formalpara>

</sect2
> <!-- gettingstarted-overview-help -->

<sect2 id="gettingstarted-overview-menu">
<title
>O que está nos menus</title>

<para
>Existem dez menus seleccionáveis na barra de menu. A maioria deles fica preenchida por completo, logo que um projecto tenha sido aberto para trabalho, enquanto outros necessitam pelo menos de um documento aberto. Em resumo, eles irão permitir os seguintes tipos de acção. </para>

<para
>Isto é apenas uma introdução. Para uma listagem mais detalhada dos menus e dos seus itens, veja a <link linkend="commands"
>Referência de Comandos</link
>.</para>

<variablelist>
  <varlistentry>
  <term
><guimenu
>Ficheiro</guimenu
></term>
  <listitem>
    <formalpara
><title
>Acções Normais</title>
    <para
>Este menu é bastante comum. Permite criar, abrir, gravar, imprimir e fechar ficheiros de documentos, assim como sair da aplicação &kdevelop;, como é normal acontecer.</para
></formalpara>
    <formalpara
><title
>Reverter as Alterações</title>
    <para
>Para além disso, permite reverter as alterações, carregando de novo o conteúdo do ficheiro de uma forma ordeira.</para
></formalpara>
  </listitem>
  </varlistentry>
  
  <varlistentry>
  <term
><guimenu
>Editar</guimenu
></term>
  <listitem>
    <para
>Este menu só é útil se estiver algum documento aberto.</para>
    <formalpara
><title
>Acções Normais</title>
    <para
>Oferece as acções normais para desfazer/refazer e para cortar/copiar/colar. Para além disso, permite seleccionar blocos de texto de várias formas.</para
></formalpara>
    <formalpara
><title
>Procurar e Substituir</title>
    <para
>Existe uma funcionalidade de procura muito poderosa disponível no menu <guimenu
>Editar</guimenu
>. Para além das acções normais de procura e substituição que se limitam ao documento actual, você poderá também conduzir uma procura e substituição a nível global. Isto permite trabalhar em todos os ficheiros do projecto de uma vez.</para
></formalpara>
    <formalpara
><title
>Edição de Texto Avançada</title>
    <para
>Existem possibilidades para formatar de novo o documento actual e para completar automaticamente alguns textos escritos parcialmente de várias formas.</para
></formalpara>
  </listitem>
  </varlistentry>
  
  <varlistentry>
  <term
><guimenu
>Ver</guimenu
></term>
  <listitem>
    <para
>Tal como no menu <guimenu
>Editar</guimenu
>, este menu só é útil se estiver algum projecto aberto de momento. Neste caso, ficarão disponíveis as seguintes acções (entre outras):</para>
    <formalpara
><title
>Histórico de Navegação</title>
    <para
>Avance e recue pelos documentos &etc; que tenha visitado.</para>
    </formalpara>
    <formalpara
><title
>Registo de Erros</title>
    <para
>Navegue pelas linhas de código dos erros que foram encontrados no último processo de compilação/construção.</para>
    </formalpara>
    <formalpara
><title
>Gerir a Janela de Ferramentas</title>
    <para
>Seleccione ou esconda as janelas de ferramentas ou as áreas acopláveis de ferramentas.</para>
    </formalpara>
    <formalpara
><title
>Acções Relacionadas com o Editor</title>
    <para
>Alguns itens do menu <guimenu
>Ver</guimenu
> controlam a aparência e comportamento do editor que você usa. No caso do componente do &kate; (Editor de Texto Avançado Incorporado), ficarão disponíveis os seguintes controlos:</para>
    </formalpara>
    <itemizedlist>
      <listitem
><para
>Controlar o comportamento de mudança de linha na janela do documento.</para
></listitem>
      <listitem
><para
>Mostrar ou esconder vários dados nas janelas de documentos: os números de linhas, ícones e, adicionalmente, as marcações de favoritos na barra de posicionamento.</para
></listitem>
      <listitem
><para
>Controlar a visibilidade das secções dobradas (temporariamente escondidas) num texto de código.</para
></listitem>
    </itemizedlist>
  </listitem>
  </varlistentry>
  
  <varlistentry>
  <term
><guimenu
>Projecto</guimenu
></term>
  <listitem>
    <para
>Todo o trabalho do &kdevelop; baseia-se em <emphasis
>projectos</emphasis
> que coleccionam basicamente os ficheiros de código, os ficheiros de gestão das compilações e outras informações numa pasta de projecto. Neste menu, poderá controlar o projecto a usar, as propriedades que tem e algumas acções de gestão. Em particular:</para>
    <formalpara
><title
>Abrir um Projecto</title>
    <para
>Permite criar projectos novos, abrir projectos existentes e importar os projectos de outros ambientes.</para>
    </formalpara>
    <formalpara
><title
>Opções do Projecto</title>
    <para
>Permite definir um conjunto completo de propriedades diferentes do projecto.</para>
    </formalpara>
    <formalpara
><title
>Gestão de Classes</title>
    <para
>Adiciona novas classes ao projecto e atravessa a árvore de heranças de uma classe.</para>
    </formalpara>
    <formalpara
><title
>Distribuir o Projecto</title>
    <para
>Ajuda a distribuir os pacotes de distribuição do projecto.</para
></formalpara>
  </listitem>
  </varlistentry>
  
  <varlistentry>
  <term
><guimenu
>Compilar</guimenu
></term>
  <listitem>
    <para
>Este menu tem a ver com tudo o que respeita à compilação e documentação do projecto. Como tal, só é usado quando está um projecto aberto de momento. Neste caso, oferece as seguintes acções:</para>
    <formalpara
><title
>Compilar, Editar as Ligações, Executar</title>
    <para
>Permite compilar e gerar o executável do projecto completo ou de partes dele, assim como executar a aplicação a partir do IDE.</para>
    </formalpara>
    <formalpara
><title
>Preparar as Operações de Compilação</title>
    <para
>Isto depende, de facto, do sistema de compilações que usa para este projecto. No caso dos projectos do 'automake', ele permite correr o <filename
>Makefile.cvs</filename
> e o <filename
>configure</filename
> por si só. Existe também a possibilidade de remover os ficheiros traduzidos do projecto em várias etapas de intensidade.</para>
    </formalpara>
    <formalpara
><title
>Instalar a Aplicação</title>
    <para
>Permite instalar a aplicação, tanto nas pastas locais como nas pastas do sistema que só estão acessíveis para o utilizador 'root'.</para>
    </formalpara>
    <formalpara
><title
>Documentação da API</title>
    <para
>Compila ou remove a documentação da API baseada no 'doxygen' do projecto, tal como está definido nas opções do projecto.</para>
    </formalpara>
  </listitem>
  </varlistentry>
  
  <varlistentry>
  <term
><guimenu
>Depuração</guimenu
></term>
  <listitem>
    <para
>Ainda que este menu seja preenchido quando está activo um projecto, só é útil de facto se o projecto actual tiver sido compilado previamente com a informação de depuração (o que é definido basicamente na opção <menuchoice
><guimenu
>Projecto</guimenu
> <guimenuitem
>Opções do Projecto..</guimenuitem
></menuchoice
>). Estão disponíveis as seguintes acções neste caso:</para>
    <formalpara
><title
>Acções Normais do Depurador</title>
    <para
>A primeira secção na opção <guimenu
>Depurar</guimenu
> oferece uma interface gráfica para o depurador simbólico GDB da &GNU;. Permite iniciar e parar a sua aplicação no depurador e percorrê-lo de várias formas.</para>
    </formalpara>
    <formalpara
><title
>Pontos de Paragem</title>
    <para
>O &kdevelop; oferece várias formas de definir pontos de paragem no código da sua aplicação. Uma delas é através da opção do menu <guimenuitem
>Comutar o Ponto de Paragem</guimenuitem
>.</para>
    </formalpara>
    <formalpara
><title
>Depuração Avançada</title>
    <para
>Outras opções do menu <guimenu
>Depurar</guimenu
> permitem uma análise mais sofisticada do programa. Use o <keycombo
><keycap
>&Shift;</keycap
><keycap
>F1</keycap
></keycombo
> para obter mais informações sobre o seu objectivo.</para>
    </formalpara>
  </listitem>
  </varlistentry>
  
  <varlistentry>
  <term
><guimenu
>Janela</guimenu
></term>
  <listitem>
    <para
>Este menu é relativamente comum. Poderá seleccionar qualquer janela de documento aberta, assim como fechar aqui uma ou mais janelas. Poderá até seleccionar um conjunto de janelas de documentos para serem fechadas de uma vez.</para>
  </listitem>
  </varlistentry>
  
  <varlistentry>
  <term
><guimenu
>Ferramentas</guimenu
></term>
  <listitem>
    <para
>O &kdevelop; é altamente personalizado. Poderá seleccionar um editor favorito para os seus documentos, assim como oferecer ferramentas externas e incorporadas para extender as capacidades básicas do IDE. O menu <guimenu
>Ferramentas</guimenu
> reflecte a maior parte desta configuração.</para>
    <formalpara
><title
>Edição Avançada</title>
    <para
>O conjunto superior dos itens do menu <guimenu
>Ferramentas</guimenu
> será oferecido pelo 'plugin' do editor em uso. Poderá seleccionar o seu editor favorito coma opção <menuchoice
><guimenu
>Configuração</guimenu
> <guimenuitem
>Configurar o KDevelop...</guimenuitem
> <guilabel
>Editor</guilabel
></menuchoice
>. Logo que tenha sido seleccionado um ficheiro de documento editável, a parte superior do menu <guimenu
>Ferramentas</guimenu
> irá oferecer comandos de edição avançados, específicos para a componente do editor em uso.</para>
    </formalpara>
    <formalpara
><title
>Tratamento da Parte Web</title>
    <para
>No caso de a janela do documento activa conter uma página em HTML (&eg; mostrada numa selecção de <guilabel
>Documentação</guilabel
>), o menu <guimenu
>Ferramentas</guimenu
> irá mostrar itens de menu adicionais que oferecem várias formas de lidar com as páginas Web.</para>
    </formalpara>
    <formalpara
><title
>Outras Ferramentas</title>
    <para
>Normalmente existirão um conjunto de outros itens, de acordo com as ferramentas disponíveis de momento. Use o <keycombo
><keycap
>&Shift;</keycap
><keycap
>F1</keycap
></keycombo
> para obter mais informações sobre os seus fins.</para>
    </formalpara>
  </listitem>
  </varlistentry>
  
  <varlistentry>
  <term
><guimenu
>Configuração</guimenu
></term>
  <listitem>
    <para
>Este menu permite-lhe mostrar e esconder o menu, as barras de ferramentas e a barra de estado. Do mesmo modo, também poderá configurar os atalhos, barras de ferramentas, notificações, o editor e o comportamento geral do KDevelop.</para>
  </listitem>
  </varlistentry>
  
  <varlistentry>
  <term
><guimenu
>Ajuda</guimenu
></term>
  <listitem>
    <para
>Aqui poderá abrir este manual do KDevelop, ler a documentação do Qt, abrir as páginas do manual (no formato tradicional de manuais do UNIX) e as páginas do 'info' (o formato de manual da GNU), comunicar erros e obter algumas informações sobre a versão actual do seu KDevelop e os seus autores.</para>
  </listitem>
  </varlistentry>
</variablelist>

</sect2
> <!--gettingstarted-overview-menu-->

</sect1
> <!-- gettingstarted-overview -->

<!--
This is covered elsewhere, so unless someone convinces me that 
it is useful to have it here as well, I will eventually delete it. Volker Paul.

<sect1 id="gettingstarted-configure">
<title
>A Bit of Configuration</title>

<para
>(- to be written -)</para>

</sect1
> 

 -->

<sect1 id="gettingstarted-new">
<title
>Como Iniciar um Projecto Novo &mdash; o &appwizard;</title>

<para
>Isto serve para lhe mostrar quão simples é pôr o KDevelop a criar um programa executável para si.</para>

<para
>O <link linkend="applicationwizard"
>&appwizard;</link
> poderá criar rapidamente um projecto para si, a partir de uma lista de modelos de projecto predefinidos. Tudo o que tem a fazer é seleccionar o tipo de projecto que deseja, como nomeá-lo e onde colocá-lo. </para>

<para
>Seleccione Projecto - Novo Projecto. A janela para Criar um Novo Projecto irá aparecer. Assumir-se-á que deseja criar um projecto normal para o KDE. Como tal, seleccione o tipo: C++ - KDE - Aplicação Simples do KDE. Indique o nome, p.ex. 'olamundo'. A localização por omissão será '/home/utilizador/olamundo'. Se terminou a configuração nesta janela, carregue em Seguinte. Na próxima janela poderá definir algumas opções que trazem já alguns valores predefinidos úteis. Carregue em Seguinte. Finalmente, será apresentado o modelo dos ficheiros .h e dos .cpp. Mais uma vez, poderá deixá-los com os valores predefinidos e carregar em Terminar. Irá ver então a mensagem a avisar que o seu programa foi criado. </para>

<para
>Para executar o seu programa, seleccione a opção Construir - Executar o Programa. Irá receber uma mensagem a avisar que o 'automake' &amp; amigos necessitam de correr primeiro. Carregue nesse caso em OK. O seu programa será então compilado e executado, e uma janela do seu novo programa irá aparecer, a dizer "Olá Mundo". Poderá agora editar o seu programa e adicionar mais algumas funcionalidades úteis. </para>

</sect1
> <!-- gettingstarted-new -->

<!-- 
Again, this will be deleted, if nobody complains.

<sect1 id="gettingstarted-edit">
<title
>Working With Documents</title>

<para
>(- to be written -)</para>

<sect2 id="gettingstarted-edit-codecompletion">
<title
>How to Automate Some Typing Tasks</title>

<para
>(- to be written -)</para>

</sect2
> 

</sect1
> 


<sect1 id="gettingstarted-compile">
<title
>How to Compile a Project</title>

<para
>(- to be written -)</para>

<sect2 id="gettingstarted-compile-messages">
<title
>What the Messages Tell</title>

<para
>(- to be written -)</para>

</sect2
> 

</sect1
> 


<sect1 id="gettingstarted-extend">
<title
>How to Extend a Project &mdash; the &automanag;</title>

<para
>(- to be written -)</para>

<sect2 id="gettingstarted-extend-automake">
<title
>A Short Look at the Automake Machinery</title>

<para
>(- to be written -)</para>

</sect2
> 

<sect2 id="gettingstarted-extend-pics">
<title
>How to Place Icons in a Separate Directory</title>

<para
>(- to be written -)</para>

</sect2
> 

<sect2 id="gettingstarted-extend-class">
<title
>How to Add New Classes</title>

<para
>(- to be written -)</para>

<caution
><para>
Be careful when you select your class file names. It is extremely difficult to change them later.
</para
></caution>

</sect2
> 

<sect2 id="gettingstarted-extend-subproject">
<title
>What is in a Subproject?</title>

<para
>(- to be written -)</para>

<sect3 id="gettingstarted-extend-subproject-active">
<title
>Concentrate on Your Work &mdash; the Active Target</title>

<para
>(- to be written -)</para>

</sect3
> 

</sect2
> 

<sect2 id="gettingstarted-extend-restructure">
<title
>Some Steps to Restructure a Project</title>

<para
>(- to be written -)</para>

</sect2
> 


</sect1
> 



<sect1 id="gettingstarted-debug">
<title
>How to Debug</title>

<para
>(- to be written -)</para>

</sect1>


<sect1 id="gettingstarted-doc">
<title
>A Note on Documentation</title>

<para
>(- to be written -)</para>

</sect1>
-->
</chapter>
