documentacion.h

   1 /* vim: set et ts=4 sw=4 fdm=indent tw=80 fdl=1 fdn=1 fo+=t:
   2  *
   3  * Taller de Programación (75.42).
   4  *
   5  * Ejercicio Número 5:
   6  * Graficador de figuras.
   7  *
   8  * Copyleft 2003 - Leandro Lucarella <llucare@fi.uba.ar>
   9  * Puede copiar, modificar y distribuir este programa bajo los términos de
  10  * la licencia GPL (http://www.gnu.org/).
  11  *
  12  * Creado: dom oct  5 20:39:33 ART 2003
  13  *
  14  * $Id$
  15  */
  16
  17 /** \mainpage Trabajo Práctico V
  18
  19 \htmlonly
  20 También puede ver <a href="../latex/refman.pdf">este documento en formato
  21 PDF</a>.
  22 \endhtmlonly
  23
  24 \latexonly
  25 También puede ver este documento en formato HTML en html/index.html.
  26 \endlatexonly
  27
  28 \section objetivo Objetivos.
  29     - Que el alumno tome contacto con las capas de API gráficas,
  30       adquiriendo la capacidad de generar gráficos simples de figuras
  31       geométricas.
  32     - Entender el concepto de Contexto Gráfico, y de las propiedades más
  33       elementales del mismo.
  34     - Manejar el concepto de Eventos, siendo el alumno capaz de armar luego
  35       programas sobra la capa de API de una funcionalidad y potencia
  36       considerables.
  37     - Comprender el concepto de ventana y dialogo.
  38     - Aplicar todos los conceptos aprendidos en la materia hasta el momento
  39       de ANSI C/C++.
  40
  41
  42 \section recursos Recursos utilizados.
  43     - Herencia y Polimorfismo.
  44     - ANSI C++ en general (para la codificación del programa).
  45     - Funciones Callback, API <a href="http://www.gtk.org/">GDK/GTK</a>.
  46
  47     \note La utilización de la API <a href="http://www.gtk.org/">GDK/GTK</a>
  48           para desarrollar el trabajo práctico bajo una plataforma libre
  49           (GNU/Linux en este caso) fue autorizada por Andrés Veiga el día
  50           30 de Septiembre de 2003.
  51
  52
  53 \section gdk_gtk Descripción de API GDK/GTK y comparación con GDI de Windows.
  54     GTK significa GIMP ToolKit ya que originalmente fue creada sólamente para
  55     hacer el programa <a href="http://www.gimp.org/">GIMP</a> (GNU Image
  56     Manipulation Program, una especie de Photoshop libre). Actualmente ha
  57     crecido mucho, hasta superando en importancia ese proyecto inicial.
  58     Creció tanto que incluso en la actualidad se compone a su vez de 2 capas
  59     más, cada una siendo de más bajo nivel que la original. La capa de más bajo
  60     nivel es la GLib, que implementa funciones básicas y tipos de datos comunes,
  61     sirviendo de capa base para hacer aplicaciones multiplataforma. Sobre ésta,
  62     está construida la biblioteca GDK (GTK+ Drawing Kit), que serviría de base
  63     para hacer aplicaciones gráficas multiplataforma (aunque fuertemente
  64     influída por la forma de funcionar de X Window, plataforma para la cual fue
  65     creada inicialmente). GDK es entoncess de relativo bajo nivel (un nivel
  66     cercano a Xlib, biblioteca de X Window, que sólo permite dibujar en pantalla
  67     y manejar eventos, como el movimiento de un mouse el presionar una tecla o
  68     un requerimiento para redibujar una porción de la pantalla). Sobre GDK se
  69     crean una serie de \e widgets (componentes como botones, etiquetas, barras
  70     de menú, etc) y a este conjunto de widgets se los llama GTK.
  71
  72
  73 \section desarrollo Desarrollo.
  74     El ejercicio consiste en un programa ejecutable utilizando las
  75     bibliotecas <a href="http://www.gtk.org/">GDK/GTK</a> que reutilizando
  76     la jerarquía de clases del Ejercicio Número 3 permita al usuario graficar
  77     por pantalla ejecutando el método dibujar de la clase Dibujo. Para ello se
  78     diseñó una ventana como la siguiente:
  79
  80     \image html  ventana.png
  81     \image latex ventana.eps "Ventana Principal"
  82
  83     En ésta el usuario puede seleccionar el tipo de figura a dibujar, los
  84     datos necesarios para dibujarla y finalmente agregarla al dibujo.
  85     El programa es capaz de agregar una figura sin dibujarla y luego dibujar
  86     todo al presionar el botón Actualizar.
  87
  88     La funcionalidad de los botones es la siguiente:
  89     - \b Actualizar: Redibuja la lista interna contenida en el dibujo.
  90     - \b Limpiar: Limpia el área de dibujo.
  91     - \b Agregar: Inserta una nueva figura al dibujo sin graficar la misma.
  92     - \b Salir: Finaliza la ejecución del programa (igual que el botón X del
  93                 manejador de ventanas).
  94
  95     Solo puede insertarse una figura a la vez y sólo se habiliten los campos
  96     correspondientes a los atributos de esa figura. Por ejemplo, si se marca
  97     el \e toggle de un Rectángulo, no se puede ingresar el Radio ya que esa
  98     figura no tiene dicho atributo.
  99
 100
 101 \section resolucion Resolución.
 102     \subsection ventana Ventana principal.
 103         Todos los componentes de la ventana principal (y la ventana en sí) se
 104         encapsularon en un objeto TP5Window. Al inicializar el objeto se
 105         inicializan todos los componentes de la ventana, inclusive el Dibujo que
 106         contiene los objetos de tipo Figura que se van agregando. Dentro de
 107         estos componentes se encuentran varios widgets GTK que se van agregando
 108         a la ventana principal, guardandose un puntero como atributo de
 109         TP5Window de solo aquellos widgets que se necesitarán a la hora de
 110         obtener la entrada del usuario. Del resto de los widgets no es necesario
 111         guardar un puntero ya que se liberan automáticamente al llamar a la
 112         función gtk_main_quit().
 113         TP5Window también tiene métodos para convertir o facilitar la conversión
 114         de los datos que ingresa el usuario.
 115         \note Para crear la ventana principal se utilizó una herramienta que
 116               gráfica que luego genera código automáticamente llamada Glade.
 117               Sobre el código generado se cambiaron varias cosas y se
 118               eliminaron llamadas a funciones inecesarias, por ejemplo. Con este
 119               programa también puede generarse un archivo XML con la disposición
 120               gráfica de todos los elementos y luego cargarlo en tiempo de
 121               ejecución mediante la biblioteca libglade, pero se dibujó toda la
 122               interfaz con código para mostrar bien por dentro el proceso
 123               realizado por dicha biblioteca.
 124
 125     \subsection callbacks Funciones callbacks.
 126         Cada evento recibido por un widget GTK (y en general cualquier señal que
 127         pueda manejar la GLib) de ser \conectado a una función callback que se
 128         encargue de menejarlo. Todas las funciones callback se agruparon en el
 129         archivo callbacks.h y callbacks.cpp. Se implementaron callbacks para los
 130         siguientes eventos:
 131         - \c expose_event:
 132             Evento \e disparado cuando se debe redibujar un área de la
 133             pantalla, en este caso sólo se conecta el evento para el área de
 134             dibujo para dibujar todas las figuras en la pantalla. La función que
 135             maneja este evento es on_drawingarea_expose_event().
 136         - \c clicked:
 137             Este evento se \e dispara cuando un GtkButton es presionado. Se usa
 138             para borrar el dibujo, actualizarlo, agregar figuras y salir del
 139             programa y es manejado por las funciones on_button__clicked() TODO
 140
 141
 142 \section requerimientos Requerimientos y modo de uso.
 143     \subsection plataforma Plataforma y compilador.
 144         Este trabajo práctico fue realizado y probado bajo la plataforma Debian
 145         GNU/Linux sid. El compilador utilizado fue GNU GCC versión 3.3.1. Se
 146         utilizó la librería GTK versión 2.2.4.
 147         El ejecutable entregado corre bajo esta plataforma y basta con
 148         ejecutarlo para ver el resultado.
 149
 150     \subsection compilacion Compilación.
 151         Para compilarlo basta con tener el programa \c make y los paquetes con
 152         librerías para desarrollo de GTK instalados (esto incluye también
 153         librerías de desarrollo de Xlib, Glib y GDK). En el caso de Debian
 154         GNU/Linux sid basta con instalar los paquetes: \c make, \c xlibs-dev,
 155         \c libglib2.0-dev, \c libgtk2.0-dev.
 156         Teniendo estos paquetes, basta ejecutar \c make para compilar el
 157         programa.
 158
 159
 160 \section conclusiones Conclusiones.
 161     TODO
 162
 163 */