# Manual do &rocs;

## Introdução

O &rocs; é um IDE da Teoria dos Grafos para todos os interessados no desenho e análise de algoritmos de grafos. Isto inclui explicitamente

- os professores que poderão demonstrar algoritmos aos seus alunos,

- os alunos que queiram compreender e ver como funciona um algoritmo,

- e todos os que tiverem de desenhar algoritmos de grafos e precisam de uma ferramenta para testar protótipos.

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.

Uma captura de tela do &rocs;. Uma captura de tela do &rocs;.

## A interface do usuário do &rocs;

### Elementos gerais da interface do usuário

A interface do usuário está dividida em várias partes lógicas, como aparece na imagem abaixo.

Elementos gráficos da interface do &rocs;. Elementos gráficos da interface do &rocs;.

Barra de ferramentas do Editor de Grafos Visual

- Para desenhar e modificar os grafos no quadro do Editor de Grafos Visual, você precisa primeiro selecionar uma ferramenta aqui

Editor de Grafos Visual

- 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.

Propriedades do grafo

- Apresenta uma lista completa com todos os diferentes grafos no quadro do Editor de Grafos Visual. Aqui você poderá fazer modificações, ⪚, 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.

Editor de script

- 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.

Resultado de depuração & script

- 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.

Execução dos scripts

- 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 Executar. Enquanto o script estiver em execução, é possível interrompê-lo se clicar no botão Parar.

### Barras de ferramentas

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:

- Barra de ferramentas principal

- Barra de ferramentas de alinhamento

#### Barra de ferramentas principal

A Barra de ferramentas principal 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:

- Mover: 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.

- Adicionar nó: Clique em uma posição arbitrária no quadro do editor do grafo para criar um novo nó que pertença ao grafo selecionado.

- Adicionar aresta: 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 (⪚, em um grafo não-direcionado, você não poderá adicionar várias arestas entre dois nós).

- Excluir: Clique em um elemento para excluí-lo. Se excluir um nó, todas as arestas adjacentes serão também excluídas.

- Ampliação: 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.

Barra de ferramentas principal. Barra de ferramentas principal.

#### Barra de ferramentas de alinhamento

Você pode adicionar a Barra de ferramentas de alinhamento opcional. Se clicar em uma ação desta barra de ferramentas, fará um efeito direto sobre os nós selecionados:

- Topo: Alinha os nós na vertical para a posição do nó superior. Isto só afeta as posições verticais.

- Centro: 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.

- Base: Alinha os nós na vertical para a posição do nó inferior. Isto só afeta as posições verticais.

- Esquerda: Alinha os nós na horizontal para a posição do nó mais à esquerda. Isto só afeta as posições horizontais.

- Centro: Alinha os nós na horizontal para a posição central do nó do tipo. Isto só afeta as posições horizontais.

- Direita: Alinha os nós na horizontal para a posição do nó mais à direita. Isto só afeta as posições horizontais.

- Círculo: 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.

- Minimizar os cantos cruzado: Aplica o algoritmo de Fruchterman-Reingold para minimizar (de forma aproximada) o número de cantos cruzados.

Barra de ferramentas de alinhamento. Barra de ferramentas de alinhamento.

### Propriedades do grafo

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.

- Nome: Este é o nome que o seu algoritmo deverá usar para acessar o grafo.

- Cor dos dados para os nós recém criados, você poderá alterar a cor do nó para todos os nós atuais, clicando no botão Tudo

- Cor dos ponteiros

A última linha de opções consiste em botões de comutação:

- Mostrar nomes em: Dados ou Ponteiros.

- Mostrar valores em: Nós ou Arestas.

## Usando o &rocs;

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 Ferramentas Gerar grafo. Eventualmente, você também pode querer usar as ferramentas auxiliares em Ferramentas Atribuir valores 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.

### Programar

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.

#### Acessando um grafo

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

Objetos do grafo

-     // funções
           array list_nodes();
           array list_edges();
           node add_node(name);
           edge add_edge(from, to);
           node node_byname(QString& name);
           node begin_node();
           array end_nodes();

      // variáveis
           bool directed
           bool automate
           string name
           string nodeDefaultColor // in HEXA
           string edgeDefaultColor  // in HEXA

Objetos de Nós

-     // 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

Objetos das arestas

-     string color ( em hexa )
          string value
          string name
          double width
          string style ( dot, dash, dash dot, solid )

          node start();
          node  end();

          void self_remove();

#### Algoritmos de grafos

À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.

Cálculo do caminho mais curto

- Calcula o caminho mais curto entre os nós início e fim. Ambos os nós deverão pertencer ao mesmo grafo. Este cálculo respeita o fato de o grafo ser direcionado ou não.

      	array dijkstra_shortest_path Node* início Node* fim

### Exemplo

Aqui está um programa simples de exemplo que altera a cor dos 4 primeiros nós do primeiro grafo:

    /* 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 < cores.length; i++){
            if (i
    > lista2.length) break;
            lista2[i].color = cores[i]
     }

### Importar e exportar

O &rocs; atualmente suporta a importação e exportação para os seguintes formatos de arquivos:

- Arquivos DOT, também conhecidos como arquivos Graphviz.

- Arquivos GML

- Arquivos de texto sem formatação.

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.

## Créditos e licença

&rocs;

Direitos autorais do programa:

- Direitos autorais 2008 Ugo Sangiori (ugorox AT gmail.com)

- Direitos autorais 2008-2011 Tomaz Canabrava (tcanabrava AT kde.org)

- Direitos autorais 2008-2011 Wagner Reck (wagner.reck AT gmail.com)

- Direitos autorais 2011 Andreas Cord-Landwehr (cordlandwehr AT googlemail.com)

Direitos autorais da documentação:

- Direitos autorais da documentação 2009 &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;

- Direitos autorais da documentação 2009 Tomaz Canabrava (tcanabrava AT kde.org)

- Direitos autorais da documentação 2011 Andreas Cord-Landwehr (cordlandwehr AT googlemail.com)

Tradução de Marcus Gamamarcus.gama@gmail.com

&underFDL; &underGPL;

## Instalação

### Como obter o &rocs;

&install.intro.documentation;

### Compilação e instalação

&install.compile.documentation;
&documentation.index;