Mdulo barra.h 2.0 para InformatE 6/7E o 6/10E
(C) 2001 Presi (Enrique D. Bosch) [kifcu@confluencia.net]
Puede distribuirse libremente bajo licencia GNU LGPL


                            MANUAL DE REFERENCIA
                            --------------------

Este es el manual de referencia que explica con detalle cada una de las
opciones, parmetros, etc. existe un tutorial rpido (fichero rapido.txt)
que explica lo bsico para crear barras de estado rpidamente, si no le has
echado un vistazo aun, te recomiendo que lo hagas.


1. Introduccin
---------------

Implementa lo necesario para crear barras de estado (lineas de estado
en argot Informate) potentes de manera sencilla.

El mdulo es biplataforma, asi que puede compilar tanto para Z como para
Glulx.

Lo primero de todo es redefinir la funcin "DibujarLineaEstado" de
Informate:

replace dibujarlineaestado;

declaracin que se debe hacer antes de incluir los ficheros de Informate, y
la inclusion de barra.h (y si procede de hora24.h) debe hacerse despus de
los includes de Informate.

include "hora24";
include "barra";

si hay que usar hora24.h, debe ser incluido antes que barra.h

La barra de estado se implementa como una clase de nombre
"objeto_barra_estado", y se declara asi

objeto_barra_estado barra_estado

redefiniendo las propiedades que sean necesarias

obviamente se le puede poner cualquier nombre distinto a "barra_estado" en
este caso, siempre y cuando todas la menciones a propiedades se hagan con el
nuevo nombre

asi mismo sera posible declarar varios objetos distintos de la clase cada
uno con propiedades distintas e independientes de modo que se podran
seleccionar las distintas barras predefinidas en tiempo de ejecucin
dependiendo de condiciones, esto se realiza cambiando la declaracin
habitual de DibujarLineaEstado:

[ dibujarlineaestado; barra_estado.dibujar(); ];

por ejemplo, supongamos que tenemos ya declarada una segunda barra de estado
"barra_estado2" y que queremos utilizarla solo en el caso de que estemos en
la localidad "casa":

[ dibujarlineaestado;

  if (localizacion==casa) barra_estado2.dibujar();
  else barra_estado.dibujar();
];



2. Propiedades del modo simple
-----------------------------

modo BE_SIMPLE     Indica que es el modo simple, si no se pone es modo
                   simple por defecto.

item               Declara el elemento a utilizar, que puede ser uno de
                   la siguiente lista:

  BE_TEXTO              texto de usuario en la propiedad "texto"
                        (si no se especifica item este ser usado por defecto)
  BE_LOCALIDAD          nombre de la localidad actual
  BE_AVENTURA           nombre de la aventura (constante historia)
  BE_HORA_24            hora en formato 24h con el texto "Hora:" delante
  BE_SOLO_HORA_24       hora en formato 24h
  BE_HORA_AMPM          hora en formato AM/PM con el texto "Hora:" delante
  BE_SOLO_HORA_AMPM     hora en formato AM/PM
  BE_TURNOS             nmero de turnos empleados (movimientos) con el 
                        texto "Movim.:" delante
  BE_SOLO_TURNOS        nmero de turnos empleados (movimientos)
  BE_PUNTUACION         puntuacin actual con el texto "Punt.:" delante
  BE_SOLO_PUNTUACION    puntuacin actual
  BE_SALIDAS            puntos cardinales que son salidas visibles con
                        el texto "Salidas:" delante
  BE_SOLO_SALIDAS       puntos cardinales que son salidas visibles

  Nota 1: Para el uso de la hora (tato en formato 24h como en AM/PM) debe
          estar incluido el mdulo hora24.h, si no est incluido, barra.h
          compilar y funcionar correctamente excepto que ignorar las
          opciones de hora.
  Nota 2: Para el uso de las salidas o las brjulas (ver BE_BRUJULA en el modo
          compuesto) debe estar definida la constante ADMITIR_COMANDO_SALIDAS
          de Informate, si no lo est no dar error, simplemente se ignorarn
          esos items.

alineacion         Establece el tipo de alineacin o justificacin del item
                   dentro de la lnea de estado, los valores pueden ser:
                   BE_IZQUIERDA (por defecto si no se especifica)
                   BE_CENTRO
                   BE_DERECHA
                   para estos dos ltimos es necesario especificar la longitud
                   aproximada del item para que el mdulo pueda centrar o
                   justificar a la derecha el texto.

longitud           Indica la longitud en caracteres (debe ser aproximada si es
                   un item no fijo que puede variar, como p. ej. el nombre de
                   localidades), es necesario para alineacion central y
                   derecha, por defecto es 0 que significa no-especificado en
                   cuyo caso el mdulo ignorar la alineacin central y
                   derecha y justificar a la izquierda.

posicion           Es la posicin vertical del item en la barra, 1 para la
                   primera lnea de la barra, 2 para la segunda, etc. en el
                   caso de que se tenga una barra multilnea, si no no hace
                   falta especificarlo ya que por defecto es 1, ver la
                   propiedad comn "lineas_inv" para barras multilnea.


3. Propiedades del modo compuesto
--------------------------------

modo BE_COMPUESTO    Activa el modo compuesto.


disposicion
   <poscin horizontal> <posicin vertical> <invertido> <item>

   La propiedad disposicin permite establecer mltiples elementos en una
   barra de estado, las caractersticas de cada elemento se expresan en
   cuatro parmetros, cada lnea de cuatro parmtros equivalen a un
   elemento. Los parmetros son:

   posicin horizontal   Es la posicin horizontal dentro de la barra
                         expresado en tanto por 80, es decir 40 siempre ser
                         el carcter central y 80 el ltimo carcter
                         independientemente del ancho real, siempre que la
                         propiedad "proporcional" est a true (valor por
                         defecto) si no, en lugar de tanto por 80 se tomar
                         la posicin como absoluta en caracteres.
                         "Posicin horizontal" puede ser tambin el valor
                         BE_JUNTO que significa que el item debe ir a
                         continuacin del anterior; nota: los textos que
                         lleven a continuacin un item con posicin
                         horizontal BE_JUNTO no deben llevar salto de lnea
                         al final, se debe utilizar 'print' el lugar de
                         su abreviatura solo con comillas ("").

   posicin vertical     Es la posicin vertical dentro de la barra: 1 para
                         la primera lnea de la barra, 2 para la segunda,
                         etc. en el caso de que se tenga una barra
                         multilnea, ver la propiedad comn "lineas_inv"
                         para barras multilnea.

   invertido             Puede ser true o false e indica si el elemento debe
                         ir en texto invertido o no, el modo invertido se
                         refiere solo al elemento, para poner en invertido
                         el resto de la lnea ver la propiedad comn
                         "lineas_inv".  El modo invertido solo funciona
                         compilando para Z, pero aunque no se use en Glulx
                         hay que especificarlo (ir mal si se omite).

   item                  Es el elemento a incluir, los items deben ser los
                         mismos que para la propiedad "item" del modo simple
                         (excepto BE_BRUJULA que es exclusivo del modo
                         compuesto).  Si se especifica ms de un item de
                         tipo BE_TEXTO la propiedad comn "texto" explicada
                         ms adelante debe ser una estructura switch.

          BE_BRUJULA            dibuja una especie de brjula (en modo
                                texto) que seala las salidas visibles, este
                                item solo funciona en el modo compuesto y
                                ocupa tres lneas de la barra a partir de la
                                posicin vertical especificada, asi que la
                                barra de estado debe tener las suficientes
                                lneas para albergar la brjula
          BE_BRUJULA_BONITA     Igual que BE_BRUJULA pero aadindole un
                                marco y las inscripciones N, S, E y O.
 
   Ejemplo:

   disposicion
     1  1 true  BE_AVENTURA
     20 1 true  BE_LOCALIDAD
     60 1 true  BE_TURNOS
     30 2 false BE_TEXTO,


numero_items         Especifica el nmero de items (lneas de la propiedad
                     disposicin) que deben tenerse en cuenta, normalmente
                     esta propiedad no se suele usar ya que el mdulo
                     detecta cuantos items hay en la propiedad "disposicion"
                     que es lo que hace cuando "numero_items" est a 0
                     (valor por defecto); solo se utilizar en el caso de
                     que se quieran variar el nmero de items en tiempo de
                     ejecucin, si incialmente hay 4 por ejemplo pero se
                     quieren utilizar luego 5, hay que 'reservar' espacio en
                     la propiedad "disposicion" para ese quinto item (con
                     ceros o con los valores reales que adoptar ese item)
                     pero si no se quiere que se tenga en cuenta aun ese
                     ltimo item es necesario poner el "numero_items" a 4
                     asi el mdulo lo ignorar ya que no queremos que se
                     represente inicialmente.


cambiar_disposicion  Es una rutina que en tiempo de ejecucin permite
                     cambiar los valores de la propiedad disposicin, si
                     bien tambin pueden cambiarse utilizando la
                     nomenclatura habitual de acceso a vectores de Inform,
                     entiendo que es mucho ms fcil proporcionar una rutina
                     que lo haga.  Los valores que hay que pasarle a son
                     (n,x,y,inv,item), "cambiar_disposicion" permite cambiar
                     los valores de un solo item en cada llamada, n es el
                     nmero de item que queremos cambiar siguiendo el orden
                     en que fueron declarados inicialmente, 1 equivaldr al
                     primero, 2 al segundo, etc., (x,y,inv,item) equivalen a
                     los valores de la propiedad disposicin posicin
                     horizontal (x), posicin vertical (y), invertido [true
                     o flase] (inv) y el item (item). No es necesario
                     cambiar todos los valores de un elemento
                     obligatoriamente, si hay alguno que no se quiere
                     cambiar se le debe dar el valor BE_NO_CAMBIAR y
                     conservar el valor que tena hasta el momento.

                     Ejemplo:
                     barra_estado.cambiar_disposicion(2,10,1,true,BE_TURNOS);

                     pone el segundo item a horizontal 10, vertical 1
                     (primera lnea), invertido a true, y mostrar los
                     turnos.


proporcional         Puede ser true (por defecto) o false, si es true el
                     valor horizontal de "disposicion" se toma como tanto
                     por 80, y se coloca proporcionalmente al ancho real, si
                     es false la posicin se toma en caracteres absolutos.



4. Propiedades comunes a ambos modos (simple y compuesto)
---------------------------------------------------------

texto               Cuando existe el item BE_TEXTO significa que se debe
                    insertar un texto fijo de usuario que se almacena en la
                    propiedad "texto", lo que se especifique ahi puede ser
                    un texto o una rutina que imprima algo (o que haga
                    cualquier otra cosa). En el modo compuesto si existe ms
                    de un item de tipo BE_TEXTO hay que especificar que
                    cadena de texto corresponde a cada item, en ese caso la
                    rutina "texto" debe ser una estructura switch indicando
                    1 para el primer item BE_TEXTO, 2 para el segundo, etc.
                    Ejemplo:

                    texto
                     [ x;
                       switch(x)
                        {
                          1: "Primer texto";
                          2: "Segundo texto";
                          3: "Tercer texto";
                        }
                     ];

                    Nota: La variable "x" puede cambiarse por cualquier otra
                    siempre que sea la misma en la cabecera de la funcin y
                    en el switch.

dibujar             Es la rutina (llamada sin parmetros) que se encarga de
                    mostrar (actualizar) la barra de estado. Si se quiere
                    que se comporte como una barra de estado normal (que se
                    actualice a cada turno) hay que llamarla desde la rutina
                    de Informate "DibujarLineaEstado" que ha sido redefinida
                    en nuestro programa.

lineas_inv          Establece el nmero de lneas de las que se compone una
                    barra (barra.h soporta barras de varias lneas) y el
                    modo de texto invetido de cada una de ellas, cada valor
                    de "lineas_inv" equivale a una lnea en la barra
                    expresando su modo, los valores pueden ser:

                    BE_INV_TOTAL     La lnea completa en modo invertido.

                    BE_INV_PARCIAL   Solo invertido el texto del item, no
                                     toda la lnea, este valor solo es
                                     vlido para el modo de barra simple
                                     (BE_SIMPLE) ya que en el compuesto cada
                                     item individualmente especifica si es
                                     invertido o no.

                    BE_INV_NO        Lnea no invertida.

                    Ejemplo:

                    lineas_inv
                      BE_INV_TOTAL
                      BE_INV_NO,

                    especifica una barra con dos lneas, la primera de ellas
                    invertida total y la segunda no invertida, por defecto
                    se define una sola lnea invertida.

                    Nota: compilando para Z, en la mayora de intrpretes el
                    marco de la barra de estado no est totalmente
                    diferenciada de la regin de texto principal, esto puede
                    hacer que al inicio de ejecucin la barra de estado, si
                    contiene ms de una lnea, sobreescriba parte del texto
                    incial, normalmente el anuncio de la aventura (el
                    ttulo, el autor, revisin, nmero de serie, etc.), para
                    evitar esto, es conveniente insertar en la funcin
                    "inicializar" un print con tantos saltos de lnea como
                    lneas contenga la barra para garantizar la
                    visualizacin del anuncio.
                    Por ejemplo, si se definiden 6 lneas:

                    lineas_inv
                      BE_INV_TOTAL
                      BE_INV_TOTAL
                      BE_INV_TOTAL
                      BE_INV_TOTAL
                      BE_INV_TOTAL
                      BE_INV_TOTAL,

                    al final de la funcin "inicializar" se debera aadir:

                    #ifdef TARGET_ZCODE;
                    print "^^^^^^";
                    #endif;

                    encerrado entre el ifdef de la mquina Z para que solo
                    compile para esta ya que para Glulx no se da el
                    problema.

numero_lineas       Declara el nmero de lneas que va a haber en la barra,
                    anlogamente a la propiedad "numero_items", si
                    "numero_lineas" es cero, barra.h detecta cuantos valores
                    hay en la propiedad "lineas_inv", solo en el caso de que
                    queramos utilizar ms durante el juego y no inicialmente
                    (o viceversa) tiene sentido la utilizacin
                    "numero_lineas" ya que habr que reservar espacio en la
                    propiedad "lineas_inv" y especificar cuantas lneas son
                    vlidas en cada momento.

cambiar_lineas_inv  Rutina que permite cambiar los valores de la propiedad
                    "lineas_inv", que tambin puede hacerse accediendo a la
                    propiedad como vector pero asi es ms fcil. A
                    "cambiar_lineas_inv" se le pasan dos parmetros: el
                    primero indica a que valor de la propiedad se refiere: 1
                    al primero, 2 al segundo, etc., el segundo valor es al
                    que hay que cambiar, que pueden ser los posibles de
                    BE_INV_TOTAL, BE_INV_PARCIAL o BE_INV_NO.

anchura             Si es cero (valor por defecto) la anchura (largaria) de
                    la barra se toma del ancho total de la pantalla
                    proporcionada por el intrprete en ejecucin.  Si se
                    pone un valor distinto de cero en esta propiedad, en
                    caracteres, fuerza que se utilice ese valor en lugar del
                    del intrprete para especificar la anchura de la barra.
                    Sobre esta anchura es sobre la que se aplican los
                    clculos para las posiciones proporcionales.  Es
                    peligroso usar esta propiedad porque en tiempo de
                    compilacin nunca sabremos con que ancho de pantalla se
                    ejecutar el programa, pero puede ser util en algunos
                    casos.


5. Agradecimientos
------------------

A todos los entusiastas de la aventura en general y a Zak (gracias por el
cdigo de la brjula) y a los de la lista Informate en particular por sus
buenas ideas.

* Nota final: si compilando da warnings sobre variables declaradas pero no
usadas, no pasa nada, es completamente normal.
