/*
 * $Id: browse.txt,v 1.1.1.1 2001/12/21 10:49:22 ronpinkas Exp $
 */

/*
 * Las siguientes partes son derechos adquiridos de sus autores individuales.
 * www - http://www.harbour-project.org
 *
 * Copyright 2000 Alejandro de Grate <alex_degarate@hotmail.com>
 * Documentacin en Espaol de: BROWSE(), DBEDIT(), TBROWSEDB(), DBSKIPPER()
 *
 * Copyright 1999 Chen Kedem <niki@actcom.co.il>
 * Documentacin en Ingls de:  BROWSE(), DBEDIT(), TBROWSEDB(), DBSKIPPER()
 *
 * Vea doc/license.txt por los trminos de la licencia.
 *
 */


/*  $DOC$
 *  $FUNCNAME$
 *      DBEDIT()*
 *  $CATEGORY$
 *      Entrada y salida de datos
 *  $ONELINER$
 *      Despliega registros en una tabla
 *  $SYNTAX$
 *      DBEDIT( [<nSup>], [<nIzq>], [<nInf>], [<nDer>], [<acColumnas>], ;
 *              [<xFuncionUsuario>], [<xColumnSayPictures>], [<xCabeceraColumna>], ;
 *              [<xSeparadorCabecera>], [<xSeparadorColumna>], ;
 *              [<xSeparadorPie>], [<xPieColumna>] ) --> lExito
 *  $ARGUMENTS$
 *      <nSup> coordenada para la fila Superior de visualizacin. El rango
 *      para <nSup> va de cero a MAXROW(), por defecto es cero.
 *
 *      <nIzq> coordenada para la columna izquierda de visualizacin. El rango
 *      para <nIzq> va de cero a MAXCOL(), por defecto es cero.
 *
 *      <nInf> coordenada para la fila inferior de visualizacin. El rango
 *      para <nInf> va de cero a MAXROW(), por defecto es MAXROW().
 *
 *      <nDer> coordenada para la columna derecha de visualizacin. El rango
 *      para <nDer> va de cero a MAXCOL(), por defecto es MAXCOL().
 *
 *      <acColumnas> es un array de expresiones de caracteres que contienen
 *      los nombres de los campos de la base de datos,o expresiones para la
 *      visualizacin en cada columna.
 *      Si no es especificada, por defecto es la visualizacin de todos los
 *      campos de la base de datos en el area de trabajo actual.
 *
 *      <xFuncionUsuario> es el nombre de una funcin  un bloque de codigo
 *      que podra ser llamado cada vez que una tecla no reconocida ha sido
 *      presionada  cuando no hay ms teclas para ser procesadas y DBEDIT()
 *      va al modo inactivo. Si <xFuncionUsuario> es una cadena de caracteres,
 *      esta debe contener el nombre de una funcin de usuario definida, que
 *      sea vlida y sin parntesis.
 *      Ambos la funcin definida por el usuario  el bloque de cdigo debern
 *      aceptar dos parmetros: nModo y nActualColumna.
 *      Ambos deberan devolver un valor numrico que corresponda a uno de
 *      los cdigos de retorno esperados.
 *      (Vea la tabla ms abajo con la lista de nModo y los cdigos de retorno)
 *
 *      <xColumnSayPictures> es un molde (picture) opcional.
 *      Si <xColumnSayPictures> es una cadena de caracteres, todas las columnas
 *      pueden usar el mismo valor como cadena de molde (picture).
 *      Si <xColumnSayPictures> es un array, cada elemento debe ser una cadena
 *      de caracteres que corresponde a la cadena (picture) usada de molde
 *      para la columna con el mismo ndice. Vea la ayuda para @...SAY para
 *      tener ms informacin acreca de los valores de molde (picture).
 *
 *      <xCabeceraColumna> contiene los titulos de cabecera para cada columna
 *      si este es una cadena de caracteres, todas las columnas tendrn el
 *      mismo encabezado, si este es un array, cada elemento es una cadena
 *      de caracteres que contienen el titulo de cabecera para cada campo.
 *      La cabecera puede ser dividido en ms de una linea al poner un punto
 *      y coma (;) en los lugares donde Ud. desea romper la linea.
 *      Si es omitida el valor por defecto para cada cabecera de columna es
 *      tomado de <acColumnas>  el nombre del campo de la base de datos, si
 *      <acColumnas> no fue especificado
 *
 *      <xSeparadorCabecera> es un array que contiene caracteres que dibujan
 *      las lineas que separan las cabeceras y los datos de los campos .
 *      En lugar de un array Ud. puede usar una cadena de caracteres que
 *      podra ser usada para la visualizacin de la misma linea para todos
 *      los campos.
 *      El valor por defecto es una linea doble.
 *
 *      <xSeparadorColumna> es un array que contiene caracteres que dibujan
 *      las lineas que separan las columnas visualizadas. En lugar de un array
 *      Ud. puede usar una cadena de caracteres que podria ser usada para la
 *      visualizacin de la misma linea para todos los campos.
 *      El valor por defecto es una linea simple.
 *
 *      <xSeparadorPie> es un array que contiene caracteres que dibujan
 *      las lineas que separan el area de datos de los campos y el pie.
 *      En lugar de un array Ud. puede usar una cadena de caracteres que
 *      podra ser usada para la visualizacin de la misma linea para todos
 *      los campos. El valor por defecto es ningn separador de pie.
 *
 *      <xPieColumna> contiene el pie para ser visualizado al final de
 *      cada columna, si este es una cadena de caracteres, todas las columnas
 *      tendran el mismo pie, si este es un array, cada elemento es una cadena
 *      de caracteres que contienen el pie para cada campo. El pie puede ser
 *      dividido en ms de una linea al poner un punto y coma (;) en los
 *      lugares donde Ud. desea romper la linea. Si es omitido ningun pie es
 *      visualizado.
 *  $RETURNS$
 *      DBEDIT() retorna .F. si no hay una base de datos abierta en ese area
 *      de trabajo,  si el nmero de columnas para la visualizacin es cero,
 *      en caso contrario DBEDIT() devuelve .T.
 *  $DESCRIPTION$
 *      DBEDIT() visualiza y permite editar registros de una  ms areas de
 *      trabajo en una grilla en pantalla. Cada columna es definida por los
 *      elementos de <acColumnas> y es el equivalente de un campo.
 *      Cada fila es el equivalente de un registro de la base de datos.
 *
 *      A Continuacin estan las teclas manejadas por DBEDIT(): </par>
 *      -------------------------------------------------------
 *     <table>
 *       Tecla            Significado
 *
 *       Izquierda        Mueve una columna a la izquierda (campo previo)
 *       Derecha          Mueve una columna a la derecha (proximo campo)
 *       Arriba           Mueve arriba una fila (registro previo)
 *       Abajo            Mueve abajo una fila (proximo registro)
 *       Pag-Arriba       Mueve a la pantalla previa
 *       Pag-Abajo        Mueve a la pantalla prxima
 *       Ctrl Pag-Arriba  Mueve al inicio del archivo
 *       Ctrl Pag-Abajo   Mueve al final del archivo
 *       Inicio           Mueve a la columna visible ms a la izquierda
 *       Fin              Mueve a la columna visible ms a la derecha
 *       Ctrl Izquierda   Desplaza una columna a la izquierda
 *       Ctrl Derecha     Desplaza una columna a la deecha
 *       Ctrl Inicio      Mueve a la columna ms a la izquierda
 *       Ctrl Fin         Mueve a la columna ms a la derecha
 *     </table>

 *      Cuando <xFuncionUsuario> es omitida, dos teclas ms estan activas:
 *     <table>
 *       Tecla            significado
 *
 *       Esc              Termina BROWSE()
 *       Enter            Termina BROWSE()
 *     </table>
 *      Cuando DBEDIT() ejecuta <xFuncionUsuario> le pasa los siguientes
 *      argumentos:
 *      nModo y el ndice del registro actual en <acColumnas>.
 *      Si <acColumnas> es omitido, el nmero de ndice es nmero de FIELD()
 *      de la estructura de la base de datos abierta.
 *
 *
 *      Valores de los Modos en DBEDIT() :    </par>
 *      ---------------------------------
 *      <table>
 *       Dbedit.ch     Valor  Significado
 *
 *       DE_IDLE        0     DBEDIT() esta inactivo, todas la teclas de
 *                            movimiento han sido procesadas.
 *       DE_HITTOP      1     Intento de mover el cursor ms alla de la parte
 *                            superior del archivo
 *       DE_HITBOTTOM   2     Intento de mover el cursor despues del final
 *                            del archivo.
 *       DE_EMPTY       3     No hay registros en el area de trabajo, la base
 *                            de datos est vacia.
 *       DE_EXCEPT      4     Interrupcin de teclado
 *      </table>
 *      La funcin definida por el usuario  el bloque de cdigo debe retornar
 *      un valor que le indique a DBEDIT() que hacer a continuacin.
 *
 *      Codigos de retorno de la Funcin del Usuario:    </par>
 *      --------------------------------------------
 *
 *      <table>
 *       Dbedit.ch   Valor   Significado
 *
 *       DE_ABORT     0      Aborta DBEDIT().
 *       DE_CONT      1      Continua DBEDIT() como ahora.
 *       DE_REFRESH   2      Fueza relectura/revisualizacin en pantalla de
 *                           todas las filas de datos
 *      </table>
 *
 *      La funcin del usuario es llamada una vez en cada uno de los
 *      siguientes casos:
 *      - La base de datos esta vaca.
 *      - El usuario trata de mover ms alla de la parte superior  de la
 *        parte inferior del archivo.
 *      - Interrupcin de teclado, el usuario ha presionado una tecla que no
 *        puede ser manejada por DBEDIT().
 *      - El buffer de teclado esta vaco  un refresco de pantalla acaba
 *        de ocurrir.
 *
 *      Nota Importante:
 *      ---------------
 *      DBEDIT() es una funcin de compatibilidad, esta fu superada por la
 *      clase TBrowse y no es recomendada para nuevas aplicaciones.
 *  $EXAMPLES$
    <fixed>
 *      // Despliega un archivo DBF usando valores por defecto
 *      USE Test
 *      DBEDIT()
 *  </fixed>
 *  $STATUS$
 *      S
 *  $COMPLIANCE$
 *      <xFuncionUsuario> puede ser tambin un bloque de cdigo, esta es una
 *      extensin de Harbour.
 *
 *      CA-Clipper lanzar un error si no hay una base de datos abierta
 *      Harbour puede retornar .F.
 *
 *      Clipper es inconsistente y lanzar un error si el nmero de columnas
 *      es cero. Harbour puede retornar .F.
 *      Las NG de CA-Clipper 5.2 indican que el valor devuelto es NIL,
 *      esto es errneo y debera ser un valor lgico.
 *
 *      Hay un cdigo de retorno (3) indocumentado para las funciones
 *      definidas por el usuario en Clipper (ambos 87 and 5.x). este es un
 *      Modo de agregado (Append) el cual:
 *      "Divide la pantalla para permitir ms que datos sean agregados en el
 *      area de la ventana".
 *      Este modo no es soportado por Harbour.
 *  $FILES$
 *      Los archivos de cabecera son dbedit.ch, inkey.ch
 *      La librera es rtl
 *  $SEEALSO$
 *     @...SAY,BROWSE(),TBrowse class,TRANSFORM()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      BROWSE()
 *  $CATEGORY$
 *      Entrada y salida de datos
 *  $ONELINER$
 *      Despliega un archivo de base de datos
 *  $SYNTAX$
 *      BROWSE( [<nSup>, <nIzq>, <nInf>, <nDer>] ) --> lExito
 *  $ARGUMENTS$
 *      <nSup> coordenada de la fila Superior de visualizacin.
 *
 *      <nIzq> coordenada de la columna izquierda de visualizacin.
 *
 *      <nInf> coordenada de la fila inferior de visualizacin.
 *
 *      <nDer> coordenada de la columna derecha de visualizacin.
 *  $RETURNS$
 *      BROWSE() retorna .F. si no hay una base de datos abierta en ese area
 *      de trabajo, en caso contrario devuelve .T.
 *  $DESCRIPTION$
 *      BROWSE() es un visualizador de bases de datos de propsito general,
 *      sin demasiado trabajo ud. puede desplegar un archivo DBF con las
 *      siguientes teclas:

 *      <table>
 *       Tecla            Significado
 *
 *       Izquierda        Mueve una columna a la izquierda (campo previo)
 *       Derecha          Mueve una columna a la derecha (proximo campo)
 *       Arriba           Mueve arriba una fila (registro previo)
 *       Abajo            Mueve abajo una fila (proximo registro)
 *       Pag-Arriba       Mueve a la pantalla previa
 *       Pag-Abajo        Mueve a la pantalla proxima
 *       Ctrl Pag-Arriba  Mueve al inicio del archivo
 *       Ctrl Pag-Abajo   Mueve al final del archivo
 *       Inicio           Mueve a la columna visible ms a la izquierda
 *       Fin              Mueve a la columna visible ms a la derecha
 *       Ctrl Izquierda   Desplaza una columna a la izquierda
 *       Ctrl Derecha     Desplaza una columna a la deecha
 *       Ctrl Inicio      Mueve a la columna ms a la izquierda
 *       Ctrl Fin         Mueve a la columna ms a la derecha
 *       Esc              Termina el BROWSE()
 *      </table>
 *
 *      En la parte superior de la pantalla ud. ve una linea de estado con
 *      la siguiente indicacin:
 *
 *      <table>
 *      Registro ###/### Nmero registro actual / Nmero Total de registros.
 *       <none>           No hay registros, el archivo esta vacio.
 *       <new>            Ud.esta en modo de Agregado al final del archivo.
 *       <Deleted>        El registro actual esta borrado.
 *       <bof>            Ud. esta en el comienzo del archivo.
 *      </table>
 *
 *      Ud. debera pasar las cuatro coordenadas validas, si menos de cuatro
 *      parmetros son pasados al BROWSE() las coordenadas por defecto son:
 *      1, 0, MAXROW(), MAXCOL().
 *  $EXAMPLES$
    <fixed>
 *      // muestra como desplegar una base de datos
 *      USE Test
 *      BROWSE()
    </fixed>
 *  $STATUS$
 *      S
 *  $FILES$
 *      La librera es rtl
 *  $SEEALSO$
 *      DBEDIT()*,TBrowse class
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      TBrowseDB()
 *  $CATEGORY$
 *      Clase TBrowse
 *  $ONELINER$
 *      Crea un nuevo objeto TBrowse para ser usado con una base de datos.
 *  $SYNTAX$
 *      TBrowseDB( [<nSup>], [<nIzq>], [<nInf>], [<nDer>] ) --> oBrowse
 *  $ARGUMENTS$
 *      <nSup> coordenada de la fila superior de visualizacin.
 *
 *      <nIzq> coordenada de la columna izquierda de visualizacin.
 *
 *      <nInf> coordenada de la fila inferior de visualizacin.
 *
 *      <nDer> coordenada de la columna derecha de visualizacin.
 *  $RETURNS$
 *      TBrowseDB() retorna un nuevo objeto TBrowse con unas coordenadas
 *      especficas y un :SkipBlock, :GoTopBlock y :GoBottomBlock por defecto
 *      para desplegar una base de datos.
 *  $DESCRIPTION$
 *      TBrowseDB() es una forma rpida de crear un objeto TBrowse junto con
 *      el soporte mnimo para desplegar una base de datos.
 *      Note que el objeto TBrowse devuelto no contiene objetos TBColumn y Ud.
 *      necesita agregar una columna para cada campo por Ud. mismo
 *  $EXAMPLES$
        <fixed>
 *      Para un buen ejemplo, mire en el cdigo fuente de la funcin BROWSE()
 *      en el subdirectorio ../source/rtl/browse.prg
        </fixed>
 *  $STATUS$
 *      S
 *  $COMPLIANCE$
 *      TBrowseDB() funciona exactamente como la funcin de CA-Clipper TBrowseDB().
 *  $FILES$
 *      La librera es rtl
 *  $SEEALSO$
 *      BROWSE(),TBColumn class,TBrowse class,TBrowseNew()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      dbSkipper()
 *  $CATEGORY$
 *      Base de datos
 *  $ONELINER$
 *      Funcin para ayudar a saltar registros en la base de datos
 *  $SYNTAX$
 *      dbSkipper( <nRecs> ) --> nSkipped
 *  $ARGUMENTS$
 *      <nRecs> es el nmero de registros a saltar relativos al registro actual.
 *      Nmeros positivos tratan de mover el puntero de registro hacia adelante
 *      y Nmeros negativos tratan de mover el puntero de registro hacia atras
 *      <nRecs> registros.
 *  $RETURNS$
 *      dbSkipper() retorna el nmero actual de registros saltados.
 *  $DESCRIPTION$
 *      dbSkipper() es una funcin de ayuda usada en el mecanismo de despliegue
 *      para saltar un nmero de registros mientras le da al llamador una
 *      indicacin del nmero actual de registros saltados.
 *  $EXAMPLES$
    <fixed>
 *      // Abre un archivo y chequea si tenemos suficientes registros en el
 *      USE ventas
 *      IF dbSkipper( 100 ) == 100
 *         ? "Buen trabajo!, debes irte de fiesta"
 *      ELSE
 *         ? "Muy mal, Ud. debera realmente trabajar ms duro"
 *      ENDIF
 *      CLOSE
      </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      dbSkipper() es una funcin de compatibilidad con XBase++ y no existe
 *      como una funcin estndar en CA-Clipper 5.x
 *      Esta funcin es solamente visible si el archivo:
 *       ../source/rtl/browdb.prg fue compilado con la bandera HB_COMPAT_XPP.
 *  $FILES$
 *      La librera es rtl
 *  $SEEALSO$
 *      DBSKIP(),SKIP
 *  $END$
 */
