<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [

  <!ENTITY kappname "&rocs;">
  <!ENTITY package "kdeedu">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % Brazilian-Portuguese "INCLUDE">
]>
<book lang="&language;">

<bookinfo>
<title
>Manual do &rocs;</title>
<authorgroup>
<author
><personname
> <firstname
>Tomaz</firstname
> <surname
>Canabrava</surname
> </personname
> <email
>tomaz.canabrava@gmail.com</email
> </author>
<author
><personname
> <firstname
>Andreas</firstname
> <surname
>Cord-Landwehr</surname
> </personname
> <email
>cordlandwehr@googlemail.com</email
> </author>

<othercredit role="translator"
><firstname
>Marcus</firstname
><surname
>Gama</surname
><affiliation
><address
><email
>marcus.gama@gmail.com</email
></address
></affiliation
><contrib
>Tradução</contrib
></othercredit
> 
</authorgroup>

<copyright
><year
>2009</year
><holder
>Tomaz Canabrava</holder
></copyright>
<copyright
><year
>2011</year
><holder
>Andreas Cord-Landwehr</holder
></copyright>

<date
>04/12/2011</date>
<releaseinfo
>1.1 &kde; 4.8</releaseinfo>

<legalnotice
>&FDLNotice;</legalnotice>

<abstract>
<para
>O &rocs; é uma ferramenta da teoria dos grafos para o KDE. </para>
</abstract>

<keywordset>
<keyword
>KDE</keyword>
<keyword
>kdeedu</keyword>
<keyword
>matemática</keyword>
<keyword
>matemática</keyword>
<keyword
>grafos</keyword>
<keyword
>nó</keyword>
<keyword
>aresta</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title
>Introdução</title>
<para
>O &rocs; é um IDE da Teoria dos Grafos para todos os interessados no desenho e análise de algoritmos de grafos. Isto inclui explicitamente</para>
<itemizedlist>
	<listitem
><para
>os professores que poderão demonstrar algoritmos aos seus alunos,</para
></listitem>
	<listitem
><para
>os alunos que queiram compreender e ver como funciona um algoritmo,</para
></listitem>
	<listitem
><para
>e todos os que tiverem de desenhar algoritmos de grafos e precisam de uma ferramenta para testar protótipos.</para
></listitem>
</itemizedlist>
<para
>Para todos estes usuários, o &rocs; oferece um editor de grafos simples de usar para definir os grafos, um mecanismo de programação em Qt Script, para executar os algoritmos, assim como diversos utilitários para configurar os seus grafos e estruturas de dados para as suas experiências. Como tal, o fluxo de trabalho normal é criar um algoritmo, criar um grafo e ver em tempo-real como funcionam os algoritmos no grafo.</para>

<screenshot>
<screeninfo
>Uma captura de tela do &rocs;.</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="rocs-screenshot.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Uma captura de tela do &rocs;.</phrase>
</textobject>
</mediaobject>
</screenshot>
</chapter>

<chapter id="user-interface">
<title
>A interface do usuário do &rocs;</title>

<sect1 id="user-interface-all">
<title
>Elementos gerais da interface do usuário</title>
<para
>A interface do usuário está dividida em várias partes lógicas, como aparece na imagem abaixo. </para>
<screenshot>
	<screeninfo
>Elementos gráficos da interface do &rocs;.</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="rocs-interfaces.png" format="PNG"/>
	</imageobject>
	<textobject>
	<phrase
>Elementos gráficos da interface do &rocs;.</phrase>
	</textobject>
	</mediaobject>
</screenshot>
<variablelist>
<varlistentry>
	<term
>Barra de ferramentas do Editor de Grafos Visual</term>
	<listitem
><para
>Para desenhar e modificar os grafos no quadro do Editor de Grafos Visual, você precisa primeiro selecionar uma ferramenta aqui</para
></listitem>
</varlistentry>
<varlistentry>
	<term
>Editor de Grafos Visual</term>
	<listitem
><para
>Esta é a área onde você poderá desenhar os seus grafos. Clique com o botão direito no quadro, nos elementos do grafo ou nos elementos selecionados do grafo para abrir um menu de contexto que dependerá do local que foi clicado.</para
></listitem>
</varlistentry>
<varlistentry>
	<term
>Propriedades do grafo</term>
	<listitem
><para
>Apresenta uma lista completa com todos os diferentes grafos no quadro do Editor de Grafos Visual. Aqui você poderá fazer modificações, &eg;, no nome do grafo, nas propriedades visíveis como os nomes ou valores dos nós ou definir as cores padrão dos elementos do grafo.</para
></listitem>
</varlistentry>
<varlistentry>
	<term
>Editor de script</term>
	<listitem
><para
>Neste editor de texto você pode criar os algoritmos em Qt Script (para os nossos propósitos, ele é essencialmente igual ao JavaScript). Você poderá trabalhar com vários algoritmos ao mesmo tempo, abrindo ou criando novas abas de scripts no menu principal. O pequeno símbolo do disco aparece se existirem alterações a serem salvas.</para
></listitem>
</varlistentry>
<varlistentry>
	<term
>Resultado de depuração &amp; script</term>
	<listitem
><para
>Esta área de texto poderá apresentar sa informações de depuração ou o resultado do script para o seu algoritmo, dependendo da configuração do resultado. Se o script emitir um erro, será selecionado automaticamente o resultado da depuração. Além disso, o resultado da depuração também apresenta todas as mensagens de resultados do script.</para
></listitem>
</varlistentry>
<varlistentry>
	<term
>Execução dos scripts</term>
	<listitem
><para
>Esta área controla a execução dos algoritmos. Você pode executar o script atualmente aberto no editor do script no grafo do quadro do Editor de Grafos Visual clicando em <guiicon
>Executar</guiicon
>. Enquanto o script estiver em execução, é possível interrompê-lo se clicar no botão <guiicon
>Parar</guiicon
>.</para
></listitem>
</varlistentry>
</variablelist>
</sect1>

<sect1 id="user-interface-toolbars">
<title
>Barras de ferramentas</title>
<para
>Existem diferentes barras de ferramentas possíveis para o editor do grafo que permitem-lhe acessar as funcionalidades apenas com um clique do mouse. Na configuração padrão são mostradas as seguintes barras de ferramentas:</para>
<itemizedlist>
	<listitem
><para
>Barra de ferramentas principal</para
></listitem>
	<listitem
><para
>Barra de ferramentas de alinhamento</para
></listitem>
</itemizedlist>

<sect2 id="user-interface-toolbars-main">
<title
>Barra de ferramentas principal</title>
<para
>A <emphasis
>Barra de ferramentas principal</emphasis
> consiste nas seguintes ações. Clicar em uma ação significa que o ponteiro do seu mouse aplica esta ação ao quadro do editor do grafo:</para>
<itemizedlist>
<listitem
><para
><guilabel
>Mover</guilabel
>: Para selecionar os elementos, você poderá clicar no espaço em branco do quadro, manter o mouse pressionado e desenhar um retângulo que contenha alguns nós e/ou arestas para selecionar estes elementos ou então clicar diretamente em um elemento não selecionado para escolher esse elemento. Se clicar em um elemento ou conjunto de elementos selecionados, você poderá mover estes elementos em conjunto. A movimentação dos elementos selecionados também é possível com as teclas direcionais.</para
></listitem>
<listitem
><para
><guilabel
>Adicionar nó</guilabel
>: Clique em uma posição arbitrária no quadro do editor do grafo para criar um novo nó que pertença ao grafo selecionado.</para
></listitem>
<listitem
><para
><guilabel
>Adicionar aresta</guilabel
>: Clique em um nó, mantenha o mouse pressionado e desenhe uma linha para outro nó, apontando a aresta nessa direção. Esta ação só será bem-sucedida se o grafo atual permitir adicionar esta aresta (&eg;, em um grafo não-direcionado, você não poderá adicionar várias arestas entre dois nós).</para
></listitem>
<listitem
><para
><guilabel
>Excluir</guilabel
>: Clique em um elemento para excluí-lo. Se excluir um nó, todas as arestas adjacentes serão também excluídas.</para
></listitem>
<listitem
><para
><guilabel
>Ampliação</guilabel
>: Clique no quadro, mantenha o &LMB; pressionado e com isto desenhe um retângulo. O quadro será ampliado para a área selecionada. É possível também usar a roda do mouse para ampliar ou reduzir. Se clicar duas vezes com o &LMB;, irá restaurar a ampliação original.</para
></listitem>
</itemizedlist>
<screenshot>
<screeninfo
>Barra de ferramentas principal.</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="rocs-toolbar-main.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Barra de ferramentas principal.</phrase>
</textobject>
</mediaobject>
</screenshot>
</sect2>

<sect2 id="user-interface-toolbars-alignment">
<title
>Barra de ferramentas de alinhamento</title>
<para
>Você pode adicionar a <emphasis
>Barra de ferramentas de alinhamento</emphasis
> opcional. Se clicar em uma ação desta barra de ferramentas, fará um efeito direto sobre os nós selecionados:</para>
<itemizedlist>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsaligntop.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Topo</guilabel
>: Alinha os nós na vertical para a posição do nó superior. Isto só afeta as posições verticais.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsalignvmiddle.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Centro</guilabel
>: Alinha os nós na vertical, com base no centro das posições verticais de todos os nós selecionados. Isto só afeta as posições verticais.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsalignbottom.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Base</guilabel
>: Alinha os nós na vertical para a posição do nó inferior. Isto só afeta as posições verticais.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsalignleft.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Esquerda</guilabel
>: Alinha os nós na horizontal para a posição do nó mais à esquerda. Isto só afeta as posições horizontais.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsalignhmiddle.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Centro</guilabel
>: Alinha os nós na horizontal para a posição central do nó do tipo. Isto só afeta as posições horizontais.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsalignright.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Direita</guilabel
>: Alinha os nós na horizontal para a posição do nó mais à direita. Isto só afeta as posições horizontais.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsaligncircle.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Círculo</guilabel
>: Alinha os nós em um círculo com o diâmetro igual à distância máxima dos nós. Estes são posicionados na mesma ordem indicada pelo centro de gravidade destes nós.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsaligntree.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Minimizar os cantos cruzado</guilabel
>: Aplica o algoritmo de Fruchterman-Reingold para minimizar (de forma aproximada) o número de cantos cruzados.</para
></listitem>
</itemizedlist>
<screenshot>
<screeninfo
>Barra de ferramentas de alinhamento.</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="rocs-toolbar-alignment.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Barra de ferramentas de alinhamento.</phrase>
</textobject>
</mediaobject>
</screenshot>
</sect2>
</sect1>

<sect1 id="user-interface-graph-properties">
	<title
>Propriedades do grafo</title>
	<para
>Na barra lateral, você poderá encontrar as opções para cada grafo aberto. Todas estas opções são globais por cada grafo, podendo ser alteradas para cada nó e aresta nas Propriedades dos nós e das janelas de Propriedades das arestas.</para>

	<itemizedlist>
	<listitem
><para
><guilabel
>Nome</guilabel
>: Este é o nome que o seu algoritmo deverá usar para acessar o grafo. </para
></listitem>
	<listitem
><para
><guilabel
>Cor dos dados</guilabel
> para os nós recém criados, você poderá alterar a cor do nó para todos os nós atuais, clicando no botão <guilabel
>Tudo</guilabel
> </para
></listitem>
	<listitem
><para>
	  <guilabel
>Cor dos ponteiros</guilabel
> <!--FIXME color of edges?-->
	</para
></listitem>
	</itemizedlist>
	<para
>A última linha de opções consiste em botões de comutação:</para>
	<itemizedlist>
	<listitem
><para
><guilabel
>Mostrar nomes em:</guilabel
> <guilabel
>Dados</guilabel
> ou <guilabel
>Ponteiros</guilabel
>. </para
></listitem>
	<listitem
><para
><guilabel
>Mostrar valores em:</guilabel
> <guilabel
>Nós</guilabel
> ou <guilabel
>Arestas</guilabel
>. </para
></listitem>
	<!-- FIXME missing Graph Type Undirected Graph, Directed Graph, Multigraph -->
	</itemizedlist>
</sect1>
</chapter>

<chapter id="using-rocs">
<title
>Usando o &rocs;</title>
<para
>Normalmente, o primeiro passo é criar um grafo com o editor de grafos visual. Você pode fazê-lo à mão, ou seja, adicionando nós e ligando-os, ou então poderá usar um dos algoritmos auxiliares que pode ser encontrado em <menuchoice
><guimenu
>Ferramentas</guimenu
> <guimenuitem
>Gerar grafo</guimenuitem
></menuchoice
>. Eventualmente, você também pode querer usar as ferramentas auxiliares em <menuchoice
><guimenu
>Ferramentas</guimenu
> <guimenuitem
>Atribuir valores</guimenuitem
></menuchoice
> para atribuir valores iniciais aos nós e arestas do grafo. Finalmente, você poderá atribuir um nome ao seu grafo. Este nome será então o identificador que deverá ser usado no mecanismo de script.</para>

<sect1 id="using-rocs-scripting">
<title
>Programar</title>
<para
>O &rocs; usa uma linguagem de script semelhante ao JavaScript. Isto é, a definição das variáveis, funções e a sua utilização é feita como no JavaScript. Além disso, o &rocs; oferece um conjunto de funções que permite-lhe acessar os grafos do quadro do editor e aos seus elementos. </para>

<sect2
><title
>Acessando um grafo</title>
<para
>Na interface de programação, você poderá acessar um grafo ao escrever o seu nome e usando-o como um objeto com uma das seguintes funções. Para acessar um nó ou aresta, você precisa obter um identificador a partir do objeto do grafo</para>
<variablelist>
<varlistentry>
<term
>Objetos do grafo</term>
<listitem>
<programlisting
>// funções
     array list_nodes();
     array list_edges();
     node add_node(name);
     edge add_edge(from, to);
     node node_byname(QString&amp; name);
     node begin_node();
     array end_nodes();

// variáveis
     bool directed
     bool automate
     string name
     string nodeDefaultColor // in HEXA
     string edgeDefaultColor  // in HEXA
</programlisting>
</listitem>
</varlistentry>

<varlistentry>
<term
>Objetos de Nós</term>
<listitem>
<programlisting
>// funções
     array adj_nodes();
     array adj_edges();
     array input_edges();
     array output_edges();
     array loop_edges();
     array connected_edges(Node *n);
     void self_remove();

// variáveis
    double x
    double y
    double width
    string value
    string name
    string color  // in HEXA
    bool begin
    bool end
</programlisting>
</listitem>
</varlistentry>

<varlistentry>
<term
>Objetos das arestas</term>
<listitem>
<programlisting
>string color ( em hexa )
    string value
    string name
    double width
    string style ( dot, dash, dash dot, solid )

    node start();
    node  end();

    void self_remove();
</programlisting>
</listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2 id="script-graph-algorithms">
<title
>Algoritmos de grafos</title>
<para
>Às vezes é útil se você puder usar funções para tarefas normais, como o cálculo das distâncias mais curtas entre dois nós. Atualmente, são suportados os seguintes algoritmos que podem ser carregados a partir do mecanismo de script para o grafo em questão.</para>
<variablelist>
<varlistentry>
<term
>Cálculo do caminho mais curto</term>
<listitem>
	<para
>Calcula o caminho mais curto entre os nós <emphasis
>início</emphasis
> e <emphasis
>fim</emphasis
>. Ambos os nós deverão pertencer ao mesmo grafo. Este cálculo respeita o fato de o grafo ser direcionado ou não.</para>
	<funcsynopsis>
	<funcprototype
><funcdef
>array <function
>dijkstra_shortest_path</function
></funcdef
> <paramdef
>Node* <parameter
><replaceable
>início</replaceable
></parameter
></paramdef
> <paramdef
>Node* <parameter
><replaceable
>fim</replaceable
></parameter
></paramdef
> </funcprototype>
	</funcsynopsis>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>

<sect1 id="script-example">
<title
>Exemplo</title>
<para
>Aqui está um programa simples de exemplo que altera a cor dos 4 primeiros nós do primeiro grafo:</para>
<programlisting
>/* Um exemplo simples que altera a cor dos 4 primeiros nós do primeiro
grafo: */

var cores = new Array("red", "green", "blue", "yellow");

/* 'grafos' é uma lista de grafos, onde você poderá acessar um grafo pelo seu índice
na lista ou pelo seu nome, assim se o nome do primeiro grafo for 'SemTitulo0',
ambas as instruções a seguir estão corretas */
var lista1= graphs[0].list_nodes(); //  1ª forma
var lista2=SemTitulo0.list_nodes();              // 2ª forma

 for ( var i = 0; i &lt; cores.length; i++){
        if (i 
> lista2.length) break;
        lista2[i].color = cores[i]
 }
</programlisting>
</sect1>
<sect1>
	<title
>Importar e exportar</title>
	<para
>O &rocs; atualmente suporta a importação e exportação para os seguintes formatos de arquivos:</para>
	<itemizedlist>
		<listitem
><para
>Arquivos DOT, também conhecidos como arquivos Graphviz.</para
></listitem>
		<listitem
><para
>Arquivos GML</para
></listitem>
		<listitem
><para
>Arquivos de texto sem formatação.</para
></listitem>
	</itemizedlist>
	<para
>Atualmente, para a maioria destes tipos de arquivos, somente alguns valores são importados. Os valores importados incluem os nós e as suas ligações correspondentes, os nomes de todos os elementos, valores e, se indicadas, as coordenadas dos nós.</para>
</sect1>
</chapter>

<chapter id="credits">
<title
>Créditos e licença</title>

<para
>&rocs; </para>
<para
>Direitos autorais do programa:</para>
<itemizedlist>
	<listitem
><para
>Direitos autorais 2008 Ugo Sangiori (ugorox AT gmail.com)</para
></listitem>
	<listitem
><para
>Direitos autorais 2008-2011 Tomaz Canabrava (tcanabrava AT kde.org)</para
></listitem>
	<listitem
><para
>Direitos autorais 2008-2011 Wagner Reck (wagner.reck AT gmail.com)</para
></listitem>
	<listitem
><para
>Direitos autorais 2011 Andreas Cord-Landwehr (cordlandwehr AT googlemail.com)</para
></listitem>
</itemizedlist>

<para
>Direitos autorais da documentação:</para>
<itemizedlist>
	<listitem
><para
>Direitos autorais da documentação 2009 &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;</para
></listitem>
	<listitem
><para
>Direitos autorais da documentação 2009 Tomaz Canabrava (tcanabrava AT kde.org)</para
></listitem>
	<listitem
><para
>Direitos autorais da documentação 2011 Andreas Cord-Landwehr (cordlandwehr AT googlemail.com)</para
></listitem>
</itemizedlist>

<para
>Tradução de Marcus Gama<email
>marcus.gama@gmail.com</email
></para
> 
&underFDL; &underGPL; </chapter>

<appendix id="installation">
<title
>Instalação</title>

<sect1 id="getting-rocs">
<title
>Como obter o &rocs;</title>
&install.intro.documentation; </sect1>

<sect1 id="compilation">
<title
>Compilação e instalação</title>
&install.compile.documentation; </sect1>
</appendix>

&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes: nil
sgml-general-insert-case: lower
sgml-indent-step:0
sgml-indent-data:nil
End:
-->
