* Mas Doc de la API

[z.facultad/75.06/emufs.git] / gui / form.h

diff --git a/gui/form.h b/gui/form.h
index ecec54d596136d09489a109f4358cd336f809a8b..82271503c165e65afa562d6e255578477a3bc55d 100644 (file)
--- a/gui/form.h
+++ b/gui/form.h
@@ -9,18 +9,42 @@
 
 #include "malloc_debug.h"
 
+/** Tipos de Widgets válidos */
 typedef enum {INPUT, RADIO} t_Campo;
 
+/** Tipo de dato Widget */
 typedef struct _elem_ {
-       char *nombre; /* nombre del widget */
-       t_Campo tipo; /* tipo */
+       /** Nombre */
+       char *nombre;
+       /** Tipo */
+       t_Campo tipo;
+       /** Dato a manejar
+        *
+        *  El dato puede ser simple o múltiple, dependiendo
+        *  si se opta por referencias valor u opciones.
+        *
+        *  Consulte la documentación de union de ANSI-C para
+        *  mas datos
+        */
        union {
-               char *valor; /* valor actual */
-               char **opciones; /* array de opciones */
+               char *valor;
+               char **opciones;
        };
-       unsigned int actual; /* En RADIO el seleccionado */
-       unsigned int max; /* INPUT: tamaño maximo RADIO: Cant. Opciones */
-       struct _elem_ *sig; /* siguiente en la lista de foco */
+       /** Elemento actual (si se utiliza valores múltiples */
+       unsigned int actual;
+       /** Máximo de elementos
+        *
+        *  El uso varía según el Widget :
+        *   INPUT : Cantidad máxima de caracteres.
+        *   RADIO : Cantidad de Opciones
+        */
+       unsigned int max;
+       /** Siguiente elemento */
+       struct _elem_ *sig;
+
+       /* Métodos */
+       int (*ejecutar)(WINDOW *win, int x, int y, struct _elem_ *w);
+       void (*destruir)(struct _elem_ *);
 } t_Widget;
 
 typedef struct _form_ {
@@ -28,15 +52,52 @@ typedef struct _form_ {
        WINDOW *win;
 } t_Form;
 
-/* Inicializa un formulario */
+/** Inicializa un formulario
+ *
+ *  \param win Ventana a la que pertenece
+ * */
 t_Form *form_crear(WINDOW *win);
-/* Libera un formulario */
+
+/** Libera un formulario */
 int form_destruir(t_Form *);
-/* Agrega un nuevo campo */
-void form_agregar_widget(t_Form *, t_Campo tipo, const char *nombre, unsigned int max, const char *defecto);
-/* Ejecuta una entrada del formulario */
-void form_ejecutar(t_Form *, int x, int y);
-char *form_obtener_valor(t_Form *, const char *widget);
+/** Agrega un nuevo campo
+ *
+ *  Significado de <em>max</em> según tipo:
+ *    INPUT : Cantidad máxima de caracteres de la entrada.
+ *    RADIO : Cantidad de opciones
+ *
+ *  Significado de <em>defecto</em> según tipo
+ *    INPUT : Nada.
+ *    RADIO : Texto separado por comas (',') de las opciones disponibles.
+ *
+ *  \param f Formulario
+ *  \param tipo Tipo de campo a agregar [INPUT|RADIO].
+ *  \param nombre Nombre del campo. Es también utilizado como etiqueta.
+ *  \param max Su uso depende del campo tipo.
+ *  \param defecto Su uso depende del campo tipo.
+ */
+void form_agregar_widget(t_Form *f, t_Campo tipo, const char *nombre, unsigned int max, const char *defecto);
+
+/** Ejecuta una entrada del formulario
+ *
+ *  Esta función va recorriendo uno por uno los campos del formulario
+ *  y dependiendo del tipo ejecutando su acción asociada.
+ *
+ *  Cuando se ha pasado por todos los campos el formulario retorna el control.
+ *
+ *  \param f Formulario.
+ *  \param x Coordenada X de inicio del formulario.
+ *  \param y Coordenada Y de inicio del formulario.
+ */
+void form_ejecutar(t_Form *f, int x, int y);
+
+/** Obtiene el valor asociado a un campo
+ *
+ *  \param f Formulario.
+ *  \param widget Nombre del campo.
+ *  \return "" Si no se encontro nada.
+ */
+char *form_obtener_valor(t_Form *f, const char *widget);
 
 #endif