/*
 * $Id: tbrowse.txt 9312 2008-09-05 00:08:34Z vszakats $
 */

/*
 * Las siguientes partes son derechos adquiridos de sus autores individuales.
 * www - http://www.harbour-project.org
 *
 * Copyright 2002 Alejandro de G rate <alex_degarate@hotmail.com>
 * Documentaci¢n en Espa¤ol de:
 *      TBrowseNew()
 *
 * Vea doc/license.txt por los t‚rminos de la licencia.
 *
 */

/*  $CLASSDOC$
 *  $FUNCNAME$
 *      TBrowseNew()
 *  $CATEGORY$
 *      Clase TBrowse
 *  $ONELINER$
 *      Crea un Objeto Browse
 *  $CONSTRUCTOR$
 *      TBrowseNew( <nArriba>,<nIzq>,<nAbajo>,<nDerecha> ) --> <oBrowse>
 *  $ARGUMENTS$
 *      <nArriba>   Fila Superior
 *
 *      <nIzq>      Columna Superior Izquierda
 *
 *      <nAbajo>    Fila Inferior
 *
 *      <nDerecha>  Columna Inferior Derecha
 *  $RETURNS$
 *      <oBrowse>  Un nuevo Objeto Browse
 *  $DESCRIPTION$
 *      Esta función establece una ventana de desplazamiento en las
 *      coordenadas establecidas por <nArriba>, <nIzq>, <nAbajo>, <nDerecha>
 *      Para visualizar una base de datos use la función TBrowseDB() en
 *      su lugar.
 *  $DATANOLINK$
 *      :aColumns       Array para guardar todas las columnas del browse
 *
 *      :autoLite       Valor Lógico para controlar el color brillante
 *
 *      :cargo          Variable definida por el usuario
 *
 *      :colorSpec      Tabla de Color para la visualización del TBrowse
 *
 *      :colPos         Columna de posición actual del cursor
 *
 *      :colSep         Caracter separador de Columnas
 *
 *      :footSep        Caracter separador de Notas al pie
 *
 *      :freeze         Número de columnas a Congelar
 *
 *      :goBottomBlock  Codeblock ejecutado por TBrowse:goBottom()
 *
 *      :goTopBlock     Codeblock ejecutado por TBrowse:goTop()
 *
 *      :headSep        Caracter separador de Encabezados
 *
 *      :hitBottom      Indica el fin de los datos disponibles
 *
 *      :hitTop         Indica el comienzo de los datos disponibles
 *
 *      :leftVisible    Indica la posición de la columna no congelada
 *                      más a la izquierda en la pantalla
 *
 *      :nBottom        Número de la Fila Inferior para la visualización
 *                      del objeto TBrowse
 *
 *      :nLeft          Columna más a la Izquierda para la visualización
 *                      del objeto TBrowse
 *
 *      :nRight         Columna más a la Derecha para la visualización
 *                      del objeto TBrowse
 *
 *      :nTop           Número de la Fila Superior para la visualización
 *                      del objeto TBrowse
 *
 *      :rightVisible   Indica la posición de la columna no congelada
 *                      más a la Derecha en la pantalla
 *
 *      :rowCount       Número de filas de datos visibles en el TBrowse
 *
 *      :rowPos         Fila de posición actual del cursor
 *
 *      :skipBlock      Codeblock usado para la reposicion de datos
 *
 *      :stable         Indica si el objeto TBrowse es estable
 *
 *      :aRedraw        Array de items lógicos indicando si es apropiado
 *                      cuales filas necesitan ser redibujadas
 *
 *      :RelativePos    Indica la posición del registro relativa a la
 *                      posición del primer registro en la pantalla
 *
 *      :lHeaders       Variable interna que indica cuando hay cabeceras
 *                      de columnas para dibujar
 *
 *      :lFooters       Variable interna que indica cuando hay pie de
 *                      columnas para dibujar
 *
 *      :aRect          El rectangulo especificado con ColorRect()
 *
 *      :aRectColor     Los colores para usar en el rectangulo especificado
 *                      con ColorRect()
 *
 *      :aKeys          Mantiene las teclas de movimiento por defecto
 *
 *  $METHODSLINK$
 *      AddColumn()     Agrega un nuevo objeto TBColumn al Browse actual
 *
 *      Applykey()      Ejecuta el movimiento de teclas del Browse
 *
 *      SetKey()        Agrega una nueva tecla al diccionario de teclado
 *  $METHODSNOLINK$
 *      New(nTop, nLeft, nBottom, nRight)
 *                        Crea una nueva clase Browse y establece los
 *                        valores por defecto
 *
 *      Down()            Mueve el cursor una fila hacia abajo
 *
 *      End()             Mueve el cursor a la columna de datos más hacia
 *                        la derecha que esté visible.
 *
 *      GoBottom()        Reposiciona los datos fuentes al final del archivo
 *
 *      GoTop()           Reposiciona los datos fuentes al inicio del
 *                        archivo
 *
 *      Home()            Mueve el cursor a la columna visible más hacia la
 *                        izquierda
 *
 *      Left()            Mueve el cursor una columna hacia la izquierda
 *
 *      PageDown()        Reposiciona los datos fuentes hacia abajo
 *
 *      PageUp()          Reposiciona los datos fuentes hacia arriba
 *
 *      PanEnd()          Mueve el cursor a la columna de datos más a la
 *                        derecha
 *
 *      PanHome()         Mueve el cursor a la columna de datos más a la
 *                        izquierda
 *
 *      PanLeft()         Se desplaza hacia la izquierda sin cambiar la
 *                        posición del cursor
 *
 *      PanRight()        Se desplaza hacia la derecha sin cambiar la
 *                        posición del cursor
 *
 *      Right()           Mueve el cursor una columna hacia la derecha
 *
 *      Up()              Mueve el cursor una fila hacia arriba
 *
 *      ColCount()        Retorna el número actual de columnas
 *
 *      ColorRect()       Altera el color de un grupo rectangular de celdas
 *
 *      ColWidth(nCol)    Retorna el ancho de visualización de una columna
 *                        particular
 *
 *      Configure( nMode)      Reconfigura los seteos internos del objeto
 *                             TBrowse. <nMode> es un parámetro no
 *                             documentado en CA-Cl*pper
 *
 *      LeftDetermine()        Determina la columna no congelada más a la
 *                             izquierda en la pantalla
 *
 *      DeHilite()             Saca el color brillante a la celda actual
 *
 *      DelColumn( nPos )      Borra un objeto Column de un Browse
 *
 *      ForceStable()          Ejecuta una estabilización total
 *
 *      GetColumn( nColumn )   Obtiene un objeto TBColumn específico
 *
 *      Hilite()               Resalta la celda actual
 *
 *      InsColumn( nPos, oCol) Inserta un objeto TBColumn de un Browse
 *
 *      Invalidate()           Fuerza un redibujo completo durante la
 *                             próxima estabilización
 *
 *      RefreshAll()           Causa que todos los datos sean recalculados
 *                             durante la próxima estabilización
 *
 *      RefreshCurrent()       Causa que la fila actual sea rellenada y
 *                             redibujada en la próxima estabilización
 *
 *      SetColumn( nColumn, oCol) Reemplaza un objeto TBColumn con otro
 *
 *      Stabilize()             Ejecuta una estabilización incremental
 *
 *      DispCell( nCol, cColor) Visualiza una sola celda en el color dado
 *
 *  $EXAMPLES$
 *      Vea el archivo ../tests/testbrw.prg
 *  $TESTS$
 *      Vea el archivo ../tests/testbrw.prg
 *  $STATUS$
 *      S
 *  $COMPLIANCE$
 *      Estas funciones son compatibles con CA-Cl*pper 5.2
 *      Los métodos Applykey() y Setkey() solamente son visibles si la
 *      compatibilidad con Clipper 5.3 ( HB_COMPAT_C53 ) está definida.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librería asociada es rtl
 *  $SEEALSO$
 *      TBROWSENEW(),TBCOLUMNNEW()
 *  $END$
 */


/*  $CLASSDOC$
 *  $METHOD$
 *      SetKey()
 *  $CATEGORY$
 *      TBrowse Method
 *  $ONELINER$
 *      Obtiene y/o Establece un bloque de código asociado a una tecla
 *  $SYNTAX$
 *      SetKey( <nTecla> [,<bBlock>] ) --> bOldBlock
 *  $ARGUMENTS$
 *      <nTecla>    Un código de tecla (inkey) válido
 *
 *      <bBlock>  Una ación opcional a asociar con el valor de la tecla
 *  $RETURNS$
 *      <bOldBlock>  Si al presionar una tecla, se cambia el codeblock
 *                   se devolverá el bloque previo, de otro modo este
 *                   método devolverá el codeblock actual.
 *  $DESCRIPTION$
 *      Este método Obtiene y opcionalmente Establece un bloque de código
 *      que es asociado con el valor de una tecla.
 *      La tabla inferior muestra las definiciones de teclas/codeblocks
 *
 *      <table>
 *      Valor Tecla    Bloque de Código
 *
 *      K_DOWN         {|Ob, nKey| Ob:Down(), 0}
 *      K_END          {|Ob, nKey| Ob:End(),  0}
 *      K_CTRL_PGDN    {|Ob, nKey| Ob:GoBottom(), 0}
 *      K_CTRL_PGUP    {|Ob, nKey| Ob:GoTop(), 0}
 *      K_HOME         {|Ob, nKey| Ob:Home(),  0}
 *      K_LEFT         {|Ob, nKey| Ob:Left(),  0}
 *      K_PGDN         {|Ob, nKey| Ob:PageDown(), 0}
 *      K_PGUP         {|Ob, nKey| Ob:PageUp(), 0}
 *      K_CTRL_END     {|Ob, nKey| Ob:PanEnd(), 0}
 *      K_CTRL_HOME    {|Ob, nKey| Ob:PanHome(), 0}
 *      K_CTRL_LEFT    {|Ob, nKey| Ob:PanLeft(), 0}
 *      K_CTRL_RIGHT   {|Ob, nKey| Ob:PanRight(),0}
 *      K_RIGHT        {|Ob, nKey| Ob:Right(), 0}
 *      K_UP           {|Ob, nKey| Ob:Up(), 0}
 *      K_ESC          {|Ob, nKey| -1 }
 *      </table>
 *
 *      Los manejadores de tecla pueden ser consultados, agregados,
 *      reemplazados y removidos del dicccionario interno de teclado.
 *      Por ejemplo
 *
 *      oTb:SETKEY( K_TAB, {|oTb, nKey| -1} )
 *
 *      Un manejador de teclas por defecto, puede ser declarado al
 *      especificar un valor de cero para <nKey>. esto asocia el codeblock
 *      que será evaluado cada vez que TBrowse:Applykey() sea llamado con
 *      un valor de tecla que no este contenida en el diccionario.
 *      Por ejemplo
 *
 *      oTb:SetKey( 0, {|oTb, nKey| DefKeyHandler( otb, nkey) })
 *      Esto llama a una función llamada DefKeyHandler() cuando nKey no
 *      está contenida en el diccionario.
 *
 *      Para remover una definición presion de tecla/codeblock, especifique
 *      NIl para <bBlock>
 *      oTb:SetKey( K_ESC, NIL )
 *  $EXAMPLES$
 *      oTb:SeyKey( K_F10, {|otb,nkey| ShowListByname(otb) }
 *  $STATUS$
 *      S
 *  $COMPLIANCE$
 *      El método Setkey() solamente es visible si la compatibilidad con
 *      Clipper 5.3 ( HB_COMPAT_C53 ) está definida.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librería asociada es rtl
 *  $SEEALSO$
 *      Applykey()
 *  $END$
 */

/*  $CLASSDOC$
 *  $METHOD$
 *      Applykey()
 *  $CATEGORY$
 *      TBrowse Method
 *  $ONELINER$
 *      Evalúa un codeblock asociado con una tecla especifica
 *  $SYNTAX$
 *      ApplyKey( <nTecla> ) --> nResultado
 *  $ARGUMENTS$
 *      <nTecla>    Un código de tecla (inkey) válido
 *  $RETURNS$
 *      <nResultado>   Valor devuelto para el codeblock evaluado
 *      Ver Tabla abajo
 *
 *      <table>
 *      Valor    Significado
 *       -1      El usuario solicita que el browse pierda foco de entrada
 *        0      El codeblock asociado con <nTecla> fue evaluado
 *        1      Imposible de localizar <nTecla> en el diccionario, la tecla
 *               no fué procesada
 *      </table>
 *  $DESCRIPTION$
 *      Este método evalúa un bloque de código asociado con <nTecla> que
 *      está contenida en el diccionario TBrowse:setkey()
 *  $EXAMPLES$
 *      WHILE .T.
 *          oTb:forceStable()
 *
 *          IF( oTb:applykey( inkey(0) ) == -1 )
 *             EXIT
 *          ENDIF
 *
 *      ENDDO
 *  $STATUS$
 *      S
 *  $COMPLIANCE$
 *      El método Applykey() solamente es visible si la compatibilidad con
 *      Clipper 5.3 ( HB_COMPAT_C53 ) está definida.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librería asociada es rtl
 *  $SEEALSO$
 *      SetKey()
 *  $END$
 */

/*  $CLASSDOC$
 *  $METHOD$
 *      AddColumn()
 *  $CATEGORY$
 *      TBrowse Method
 *  $ONELINER$
 *      Agrega una nueva Column a un Objeto TBrowse
 *  $SYNTAX$
 *      AddColumn( oCol ) --> Self
 *  $ARGUMENTS$
 *      <oCol>  Es un Objeto TBColumn
 *  $RETURNS$
 *      <Self>  El Objeto actual
 *  $DESCRIPTION$
 *      Este método agrega un nuevo Objeto TBColumn especificado como <oCol>
 *      al objeto de browsing asignado.
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Esta función es compatible con CA-Cl*pper 5.2
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      La librería asociada es rtl
 *  $SEEALSO$
 *      TBColumnNew()
 *  $END$
 */


