Passo a Passo


= Passo a Passo =

Neste capítulo, inicialmente, é feito um comparativo entre a execução de um
algoritmo normal; recurso já existente no **GRAFO**; e a execução de um algoritmo //passo a passo//,
novo recurso introduzido por este trabalho. também são explicados os recursos existentes no //passo a passo// e como
o usuário pode interagir com um algoritmo. Em seguida é abordado
como o este foi implementado e o que motivou esta abordagem. O capítulo
termina mostrando um tutorial prático de como se realiza a implementação um plugin com funcionalidade
//passo a passo//. Para tanto abordou-se neste tema também os //headers// necessários, as estruturas
internas e os cuidados que devem ser tomados para sua construção.

== Como estava ==

O que é o //passo a passo//?
É a possibilidade de interagir com a execução do algoritmo. E com isso conseguir
uma visão melhor de como e o que ele faz do seu início ao fim.

A possibilidade de execução de algoritmos //passo a passo// veio preencher uma 
lacuna deixada pelo **GRAFO**. Na estrutura de execução que existia até
então era difícil observar o que se passava entre o início (click no menu) e o fim do algoritmo
(atualização da área de trabalho).

Observemos a execução do algoritmo //Depth First - Busca em profundidade//, sem
suporte a //passo a passo//, no menu //Algorithms > Search algorithms > Depth First//.

Na figura (5.1) observa-se um //grafo// em árvore com 6 vértices. Ao executar o 
algoritmo em segundos todos os vértices e arestas da árvore são destacados. Vide figura (5.2).
Como a árvore foi completamente destacada? Qual a ordem que os vértices foram destacados? 
Quantos passos têm esse algoritmo? Sem o conhecimento prévio de como funciona a 
busca em profundidade em uma árvore é impossível responder a tais perguntas. 

| [images/05-PassoAPasso-01-Arvore.png] | [images/05-PassoAPasso-02-Arvore-AposBusca.png]
| (figura 5.1)                          | (figura 5.2)


== Como ficou ==

Foi justamente com o objetivo de responder a estas perguntas que entra a execução de algoritmo //passo a passo//
na interface do **GRAFO**. Ele vem auxiliar a compreensão e o entendimento
da execução de algoritmos de uma maneira visual e interativa.

Observemos a execução do mesmo algoritmo //Depth First - Busca em profundidade//, porém
com suporte a //passo a passo//, no menu //Algorithms > Algorithms step by step > Depth First//.

Na figura 5.3 observa-se o mesmo //grafo// em árvore com 6 vértices. Ao executar
o algoritmo o //grafo// vai lentamente sendo destacado. Vide figura 5.4 até figura 5.9.
Com esta visualização mesmo um leitor leigo consegue responder as perguntas feitas.

Como a árvore foi completamente destacada?
 - De cima para baixo da esquerda para a direita.
 
 
Qual a ordem que os vértices foram destacados?
 - 0, 2, 4, 3, 1, 5
 
 
Quantos passos tem esse algoritmo? 
 - 6 passos desde a marcação do primeiro vértice.
  
| [images/05-PassoAPasso-03-Arvore-Passo0.png]
| (figura 5.3)
| [images/05-PassoAPasso-04-Arvore-Passo1.png] | [images/05-PassoAPasso-05-Arvore-Passo2.png] | [images/05-PassoAPasso-06-Arvore-Passo3.png]
| (figura 5.4)                                 | (figura 5.5)                                 | (figura 5.6                     
| [images/05-PassoAPasso-07-Arvore-Passo4.png] | [images/05-PassoAPasso-08-Arvore-Passo5.png] | [images/05-PassoAPasso-09-Arvore-Passo6.png]
| (figura 5.7)                                 | (figura 5.8)                                 | (figura 5.9)


== Interagindo com o algoritmo ==

Através da //barra de ferramentas//, figura 5.10, é possível uma interação básica com o algoritmo.
Ao acionar o algoritmo pelo menu ele lentamente vai sendo executado, porem é possível
através dos botões ir direto ao resultado final, voltar ao começo, ir somente
um passo a diante, retroceder um passo ou colocá-lo para executar //passo a passo// novamente.

[images/05-PassoAPasso-10-Toolbar.png]

(figura 5.10)

 - **First Step**
 
  Retorna o primeiro passo gravado. 
 
 - **Prev Step**

  Retorna o passo anterior. 
 
 - **Execute**
 
  Inicia a execução passo a passo em modo automático. 
 
 - **Next Step**

  Avança para o próximo passo.  
 
 - **Last Step**
 
  Avança para o último passo gravado. 


== Como foi implementado ==

A idéia inicial foi implementar a interface //passo a passo// de uma forma genérica 
sem que fosse necessária intervenção explícitas nos algoritmo. E assim todo e qualquer algoritmo
no **GRAFO** poderia ser executado com ou sem o //passo a passo//, porem devido a modularidade
do programa fez com que essa abordagem não fosse possível. No **GRAFO** existe uma
clara divisão entre o que é interface com o usuário, estrutura de desenho,
estrutura de //grafos// e estrutura de plugins e algoritmos. Os algoritmos nativos
ou por plugins não têm acesso direto a interface com o usuário e a estrutura de desenho. 
Ao serem executados eles se preocupam em manipular grafos, arestas e vértices. O reflexo
desta alterações ao usuário é feito pela estrutura de desenho em conjunto com a interface.

A estratégia adotada foi de que os algoritmos continuassem a manipular
somente o que eles conhecem, que são grafos, arestas e vértices, para isto, foi
criado um mecanismo de gravação e reprodução de estados. A cada estado interessante
o algoritmo explicitamente grava a situação do grafo e das listas de destaque de
vértices e arestas. Ao concluir a execução temos um filme com os passos relevantes
para a compreensão do algoritmo. E este filme é disponibilizado ao usuário.

== Headers ==

Para criar o mecanismo de gravação e reprodução utilizou-se uma lista onde cada nodo contém em que contexto
está o //grafo//, arestas e vértices em destaque no momento que se instrui a gravação. Abaixo segue as
estruturas e funções implementadas para tratar o //passo a passo//.

**//step.h//**

O //header// //step.h// deve ser incluído em um plugin sempre que se desejar que este 
tenha os recursos do //passo a passo//

**Step struct** - Estrutura de um passo

A estrutura //Step// (tabela 5.1) contém as informações necessárias a um passos que são: 
O seu identificador, uma cópia do grafo, os vértices em destaque, as arestas em destaque e 
uma mensagem associada ao passo salvo.

|| Nome             | Tipo           | Descrição                                           |  
| ``id``            | ``int``        | Identificador do passo. Auto incremental e único    |
| ``G``             | ``Graph``      | //Grafo// associado ao passo                        |
| ``SpecEdges``     | ``List *``     | Lista de destaque de arestas associadas ao passo    |
| ``SpecVerts``     | ``List *``     | Lista de destaque de vértices associados ao passo   |
| ``status_string`` | ``char[1000]`` | Mensagem para a barra de status associada ao passo  |
(tabela 5.1)

**StepStruct struct** - Estrutura de múltiplos passos

A estrutura //StepStruct// (tabela 5.2) contém as informações necessárias para a reprodução 
dos passo: A quantidade de passos salvos, o passo atual, a lista de passos salvos
e o status da execução do //passo a passo//.

|| Nome             | Tipo                | Descrição                                                     |  
| ``size``          | ``int``             | Número de passos gravados                                     |
| ``index``         | ``int``             | Contador de passo. Informa o passo atual                      |
| ``steps``         | ``Step[MAX_STEPS]`` | Lista contendo os passos gravados                             |
| ``exec_state``    | ``char``            | Status de execução ``(EXECUTING_STEPS, NOT_EXECUTING_STEPS)`` |
(tabela 5.2)

**Functions** - Funções para manipulação do //passo a passo//

A tabela 5.3 traz a lista de funções para manipulação do passo a passo. 
A função //AddStep// é a única de uso externo, através de plugins, as demais são
de uso interno a implementação do //passo a passo//. Um algoritmo somente deve-se 
preocupar em salvar os passos através do //AddStep// a inicialização da estrutura //Step// e //StepStruct// e o início automático
da execução são atribuições da interface do **GRAFO**.

|| Declaração                                                         | Descrição                                                                                                             |  
| ``void InitStepStruct(void)``                                       | Inicializa a estrutura passo a passo                                                                                  |
| ``void AddStep(Graph *G, List *arc_edges, List *verts)``            | Adiciona o //grafo// ``G`` e as listas ``arc_edges`` e ``verts`` no próximo passo livre                               |
| ``void ShowStep(Graph *G, List *arc_edges, List *verts, int step)`` | Vai para o passo informado e o copia para a interface o //grafo// ``G`` e as listas ``arc_edges`` e ``verts``         |
| ``void FirstStep(Graph *G, List *arc_edges, List *verts)``          | Vai para o primeiro passo gravado e o copia para a interface o //grafo// ``G`` e as listas ``arc_edges`` e ``verts``  |
| ``void PreviousStep(Graph *G, List *arc_edges, List *verts)``       | Vai para o passo anterior e o copia para a interface o //grafo// ``G`` e as listas ``arc_edges`` e ``verts``          |
| ``void NextStep(Graph *G, List *arc_edges, List *verts)``           | Vai para o próximo passo e o copia para a interface o //grafo// ``G`` e as listas ``arc_edges`` e ``verts``           |
| ``void LastStep(Graph *G, List *arc_edges, List *verts)``           | Vai para o último passo e o copia para a interface o //grafo// ``G`` e as listas ``arc_edges`` e ``verts``            |
| ``int GetLastStep(void)``                                           | Retorna o número de passos gravados                                                                                   |
| ``char GetExecStateStep(void)``                                     | Retorna se o //passo a passo// está em execução ``(EXECUTING_STEPS, NOT_EXECUTING_STEPS)``                            |
| ``void SetExecStateStep(char state)``                               | Inicia e termina a execução do //passo a passo// ``(START_EXEC_STEPS, STOP_EXEC_STEPS)``                            |
(tabela 5.3)


== Construindo um algoritmo passo a passo ==

Como exemplo prático será construído o plugin //Select odd// que tem como
característica destacar todos os vértices ímpares e todas as arestas que conectam
vértices ímpares. O código fonte completo do plugin //Select odd// encontra-se no Apêndice B.

No capítulo 4 foi abordada a construção de plugins. Neste capítulo iremos complementá-la com a possibilidade de plugins //passo a passo//.
Como no plugin comum o //passo a passo// também é dividido em 3 partes. São elas:

+ Inclusão de //headers//
+ Protótipo das funções
+ Corpo das funções


=== headers ===

Na primeira parte deve-se incluir os //headers// da linguagem C e os //headers// obrigatórios
para todos os plugins e mais o //header// //step.h// obrigatório para o //passo a passo//:

%!include(html): ''include/05-PassoAPasso-01-headers-selectoddexample.c.html'' 

=== Protótipo das funções ===

Na segunda parte  declara-se o protótipo para a função obrigatória //pgin_info//
e o protótipo para as funções de algoritmos e outras funções.
Como função de algoritmo foi declarada a //SelectOdd//.

%!include(html): ''include/05-PassoAPasso-02-prototype-selectoddexample.c.html'' 

Como mencionado no capítulo 4 cada tipo de algoritmo possui uma assinatura diferente para a lista de parâmetros (tabela 5.4).
Para algoritmos //passo a passo// temos:

+ Step by step

```
int StepAlgorithm(Graph *G, char *mess, int indx, List *arc_edges, List *verts)
```

|| Parâmetros         | Descrição                                                         |  
| ``Graph *G``        | Aponta para //grafo// na área de trabalho                         |
| ``char *mess``      | Aponta para a mensagem na barra de status                         |
| ``int indx``        | Número do vértice inicial de buscas                               |
| ``List *arc_edges`` | Lista com as arestas destacadas do //grafo// na área de trabalho  |
| ``List *verts``     | Lista com os vértices destacados do //grafo// na área de trabalho |
(tabela 5.4)

=== Corpo das funções ===

Análogo a algoritmos tradicionais a terceira parte deve-se criar o corpo para a função obrigatória //pgin_info// e implementar
as funções do algoritmo.

**//pgin_info//** - Função obrigatória

A //pgin_info// deve adicionar a lista de algoritmos com o tipo correto para algoritmos //passo a passo// que é //PGIN_STEP_ALG//.

%!include(html): ''include/05-PassoAPasso-03-mandatory-selectoddexample.c.html'' 

**//SelectOdd//** - Funções de algoritmos

A função //SelectOdd// deve-se preocupar em gravar passos que ilustram a execução do algoritmo, os passos gravados que serão disponibilizado para a interação do usuário.

%!include(html): ''include/05-PassoAPasso-04-main-selectoddexample.c.html'' 

No algoritmo //Select odd// foi utilizado três vezes a chamada da função //AddStep//. A
primeira vez se preocupa em salvar contexto do //grafo// sem o destaque de vértices
e arestas. A segunda chamada se preocupa em salvar o momento que vértices ímpares são
inseridos na lista especial //verts//. A terceira chamada se preocupa em salvar o 
momento em que as arestas são inseridas na lista especial //arc_edges//. A segunda chamada da função 
//AddStep// poderia ser suprimida. E com isso os vértices e arestas apareceriam
em destaque no //passo a passo// em conjunto. Com isso concluímos que o posicionamento
da chamada //AddStep// no algoritmo é essencial para sua compreensão. No exemplo
o que se deseja é mostrar que primeiramente todos os vértices impares são destacados e depois
que todas as arestas entre vértices ímpares são destacadas.

Um outro cuidado que se deve ter é de não salvar passos adicionais ou repetidos
que não acrescentem em nada a compreensão do algoritmo. No exemplo utiliza-se a
propriedade //mark// para informar que uma aresta já foi destacada. Por exemplo
se foi salvo o passo quando a aresta (1,3) é destacada não existe a necessidade de 
salvar o passo (3,1) pois a aresta é a mesma. Abaixo segue o trecho de código
que faz este controle.

%!include(html): ''include/05-PassoAPasso-05-main-01-pice-selectoddexample.c.html'' 
%!include(html): ''include/05-PassoAPasso-06-main-02-pice-selectoddexample.c.html'' 

== Compilação e Instalação ==

O procedimento de compilação deve ser reproduzido para os plugins //passo a passo//.

+ Compilação

Para compilar o plugin de exemplo //SelectOdd// que está no arquivo //selectoddexample.c// utilizamos:

```
gcc -Wall -fPIC -shared selectoddexample.c -o selectoddexample.so
```
+ Instalação

Para instalar copiamos a biblioteca gerada (//selectoddexample.so//) para o diretório 
de plugins.


== Execução ==

Ao abrir o **GRAFO** o novo plugin estará disposto abaixo do menu //Algorithms  > Algorithms step by step// vide
figura 5.11.

[images/05-PassoAPasso-11-Menu.png]

(figura 5.11)

Ao clicar no menu //Select odd// o **GRAFO** chama a função de algoritmo associado a ele, o algoritmo é
executado gravando todos os passos relevantes, e ao término o **GRAFO** exibe lentamente o resultado
(Figura 5.12 até 5.20). Observando-se os passos pode-se ter uma idéia de como o
algoritmo //Select odd// foi construído. Primeiro são destacados todos os vértices
ímpares do menor para o maior //{1, 3, 5, 7}//. E depois todas as arestas entre vértices ímpares 
do menor vértice para o maior //{(1,7), (3,5), (3,7), (5,7)}//.

| [images/05-PassoAPasso-12-Odd-Passo0.png] | [images/05-PassoAPasso-13-Odd-Passo1.png] | [images/05-PassoAPasso-14-Odd-Passo2.png]
| (figura 5.12)                             | (figura 5.13)                             | (figura 5.14)
| [images/05-PassoAPasso-15-Odd-Passo3.png] | [images/05-PassoAPasso-16-Odd-Passo4.png] | [images/05-PassoAPasso-17-Odd-Passo5.png]
| (figura 5.15)                             | (figura 5.16)                             | (figura 5.17)
| [images/05-PassoAPasso-18-Odd-Passo6.png] | [images/05-PassoAPasso-19-Odd-Passo7.png] | [images/05-PassoAPasso-20-Odd-Passo8.png]
| (figura 5.18)                             | (figura 5.19)                             | (figura 5.20)



