/*
 * $Id: command.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 2000 Alejandro de Grate <alex_degarate@hotmail.com>
 * Documentacin en Espaol de los comandos OOP
 *
 * Copyright 2000 Brian Hays <bhays@abacuslaw.com>
 * Documentacin en Ingls de los comandos OOP
 *
 * Vea doc/license.txt por los trminos de la licencia.
 *
 */


/*  $DOC$
 *  $COMMANDNAME$
 *      CLASS
 *  $CATEGORY$
 *      Comando OOP
 *  $ONELINER$
 *      Define una Clase para la Programacion Orientada a Objetos (OOP).
 *  $SYNTAX$
 *      CLASS <NombreClase> [ <FROM, INHERIT> <SuperClase> ]
 *  $ARGUMENTS$
 *      <NombreClase> Nombre de la clase a definir. Por tradicin, las
 *                    clases en Harbour comienzan con "T" (algo comn en el
 *                    mundo OOP) para evitar colisiones con clases creadas
 *                    por el usuario.
 *      <SuperClase>  La clase padre para usar la herencia.
 *  $DESCRIPTION$
 *      CLASS crea una clase desde la cual se pueden crear objetos.
 *      Cada clase es definida en un archivo.prg separado para este propsito
 *      No se puede crear ms de una clase en un archivo.prg
 *      Despus del mandato CLASS comienza la definicin, luego los elementos
 *      DATA (tambien conocidos como variables de instancia) y luego
 *      los METHODS de la clase (el equivalente a las funciones en la
 *      Programacion tradicional)
 *
 *      Las Clases pueden heredar desde una clase sola <SuperClass>, pero la
 *      cadena de herencia puede extenderse a muchos niveles
 *
 *      Un program usa una clase llamando al Constructor de la clase, el
 *      mtodo New() para crear el objeto. Ese objeto es usualmente asignado
 *      a una variable, la cual es usada para acceder a los elementos DATA
 *      y a los mtodos
 *  $EXAMPLES$
 *      <fixed>
 *      CLASS TBColumn
 *
 *         DATA Block      // Codeblock para recuperar datos para la Columna
 *         DATA Cargo      // Variable definida por el usuario
 *         DATA ColorBlock // Codeblock que determina el color de los items
 *         DATA ColSep     // Caracter separador de la Columna
 *         DATA DefColor   // Array de ndices numricos a la tabla de color
 *         DATA Footing    // Pie de Columna
 *         DATA FootSep    // Caracter separador del Pie
 *         DATA Heading    // Encabezado de la Columna
 *         DATA HeadSep    // Caracter separador de la cabecera
 *         DATA Width      // Ancho de la Columna
 *         DATA ColPos     // Posicin temporaria de la columna en pantalla
 *
 *         METHOD New()    // Constructor
 *
 *      ENDCLASS
 *      </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      CLASS es una extensin de Harbour.
 *  $PLATFORMS$
 *      Todas
 *  $SEEALSO$
 *      HBClass(),Programacion Orientada a Objeto,DATA,METHOD
 *  $END$
 */

/*  $DOC$
 *  $COMMANDNAME$
 *      DATA
 *  $CATEGORY$
 *      Comando OOP
 *  $ONELINER$
 *      Define una variable de instance DATA, para los objetos de la clase
 *  $SYNTAX$
 *      DATA <NombreDato1> [,<NombreDatoN>] [ AS <tipo> ] [ INIT <uValor> ]
 *  $ARGUMENTS$
 *      <NombreDato1> Nombre de DATA
 *
 *      <tipo>        Especificacin Opcional del tipo de datos, de uno de
 *                    los siguientes (especificacin en ingls):
 *                    Character, Numeric, Date, Logical, Codeblock, Nil
 *
 *      <uValor>      Valor opcional inicial cuando se crea un nuevo objeto
 *  $DESCRIPTION$
 *      Los elementos DATA tambien pueden ser pensados como "propiedades"
 *        "atributos" de un objeto. ellos pueden ser de cualquier tipo
 *      incluyendo bloques de codigo.
 *      Una vez que el objeto ha sido creado, los elementos DATA son refe-
 *      renciados con dos puntos (:) como en MyObject:Heading := "Nombre".
 *      Usualmente una clase tambin define mtodos para manipular los DATA.
 *
 *      Se puede usar la clausula "AS <type>" para reforzar que DATA es
 *      perteneciente a un cierto tipo. De otra manera este tomar el tipo
 *      de cualquier valor que le sea asignado.
 *
 *      Use la clausula "INIT <uValue>" para inicializar ese DATA a <uValue>
 *      siempre que un nuevo objeto es creado.
 *  $EXAMPLES$
 *      <fixed>
 *      CLASS TBColumn
 *
 *         DATA Block      // Codeblock para recuperar datos para la Columna
 *         DATA Cargo      // Variable definida por el usuario
 *         DATA ColorBlock // Codeblock que determina el color de los items
 *         DATA ColSep     // Caracter separador de la Columna
 *         DATA DefColor   // Array de ndices numricos a la tabla de color
 *         DATA Footing    // Pie de Columna
 *         DATA FootSep    // Caracter separador del Pie
 *         DATA Heading    // Encabezado de la Columna
 *         DATA HeadSep    // Caracter separador de la cabecera
 *         DATA Width      // Ancho de la Columna
 *         DATA ColPos     // Posicin temporaria de la columna en pantalla
 *
 *         METHOD New()    // Constructor
 *
 *      ENDCLASS
 *      </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      DATA es una extensin de Harbour.
 *  $PLATFORMS$
 *      Todas
 *  $SEEALSO$
 *      Programacion Orientada a Objeto,CLASS,METHOD,CLASSDATA
 *  $END$
 */

/*  $DOC$
 *  $COMMANDNAME$
 *      CLASSDATA
 *  $CATEGORY$
 *      Comando OOP
 *  $ONELINER$
 *      Define una variable CLASSDATA para una clase (NO para un Objeto !)
 *  $SYNTAX$
 *      CLASSDATA <DataName1> [,<DataNameN>] [ AS <type> ] [ INIT <uValue> ]
 *  $ARGUMENTS$
 *      <NombreDato1> Nombre de DATA
 *
 *      <tipo>        Especificacin opcional del tipo de datos de uno de
 *                    los siguientes (Original en ingls):
 *                    Character, Numeric, Date, Logical, Codeblock, Nil
 *
 *      <uValor>      Valor opcional inicial cuando se inicia el programa
 *  $DESCRIPTION$
 *      Las variables CLASSDATA pueden se pensadas como "propiedades" de un
 *      clase entera. Cada CLASSDATA existe slo una vez, no importa cuntos
 *      objetos sean creados. Un uso comun es para un contador que es
 *      incrementado siempre que un objeto es creado y decrementado cuando
 *      alguno es destruido, as se puede monitorear el nmero de objetos
 *      en existencia para esta clase.
 *
 *      Se puede usar la clausula "AS <type>" para reforzar que CLASSDATA es
 *      perteneciente a un cierto tipo. De otra manera este tomar el tipo
 *      de cualquier valor que le sea asignado.
 *      Use la clausula "INIT <uValue>" para inicializar ese DATA a <uValue>
 *      siempre que un nuevo objeto es creado.
 *  $EXAMPLES$
 *      <fixed>
 *      CLASS TWindow
 *         DATA   hWnd, nOldProc
 *         CLASSDATA lRegistered AS LOGICAL
 *      ENDCLASS
 *      </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      CLASSDATA es una extensin de Harbour.
 *  $PLATFORMS$
 *      Todas
 *  $SEEALSO$
 *      Programacion Orientada a Objeto,CLASS,METHOD,DATA
 *  $END$
 */

/*  $DOC$
 *  $COMMANDNAME$
 *      METHOD
 *  $CATEGORY$
 *      Comando OOP
 *  $ONELINER$
 *      Declara un METHOD para una clase en la cabecera de la clase
 *  $SYNTAX$
 *      METHOD <NombreMtodo>( [<params,...>]) [ CONSTRUCTOR ]
 *      METHOD <NombreMtodo>( [<params,...>]) INLINE <Code,...>
 *      METHOD <NombreMtodo>( [<params,...>]) BLOCK  <CodeBlock>
 *      METHOD <NombreMtodo>( [<params,...>]) EXTERN <FuncName>([<args,..>])
 *      METHOD <NombreMtodo>( [<params,...>]) SETGET
 *      METHOD <NombreMtodo>( [<params,...>]) VIRTUAL
 *      METHOD <NombreMtodo>( [<param>] )     OPERATOR <op>
 *      METHOD <NombreMtodo>( [<params,...>]) CLASS <ClassName>
 *  $ARGUMENTS$
 *      <NombreMtodo>  Nombre del mtodo a definir
 *
 *      <params,...>    Lista opcional de parametros
 *  $DESCRIPTION$
 *      Los Mtodos son "funciones de clase" y hacen el trabajo de la clase.
 *      Todos los mtodos pueden ser definidos en la cabecera entre los
 *      comandos CLASS y ENDCLASS. Si el cuerpo de un mtodo no esta
 *      totalmente definido aqui, el cuerpo completo es escrito debajo del
 *      comando ENDCLASS usando esta sintaxis:
 *
 *         METHOD <NombreMtodo>( [<params,...>] ) CLASS <NombreClase>
 *
 *      Los Mtodos pueden referenciar al objeto actual usando la palabra
 *      clave "Self:"  su versin ms corta "::"
 *
 *      CLAUSULAS:
 *
 *      CONSTRUCTOR  Define un mtodo especial de la clase: el mtodo
 *                   Constructor, usado para crear objetos. Este es
 *                   usualmente el mtodo New().
 *                   Los constructores siempre retornan el objeto New().
 *
 *      INLINE       Rpido y fcil de codificar, INLINE le permite definir
 *                   el cdigo para el mtodo inmediatamente despus de la
 *                   definicin de la clase. Cualquier mtodo no declarado
 *                   INLINE  BLOCK debe ser completamente definido despus
 *                   del comando ENDCLASS.
 *                   El <Codigo,...> siguiente a INLINE recibe un parametro
 *                   de Self. Si se necesita recibir ms parmetros, use
 *                   la clusula BLOCK en su lugar.
 *
 *      BLOCK        Use esta clusula cuando desee declarar rpidos mtodos
 *                   'inline' que necesiten parmetros. El primer parmetro
 *                    a <CodeBlock> debe ser Self, como en:
 *
 *          METHOD <NombreMtodo> BLOCK {|Self,<arg1>,<arg2>,...,<argN>|...}
 *
 *      EXTERN       Si una funcin externa hace lo que el mtodo necesita,
 *                   use esta clusula para hacer una llamada optimizada a
 *                   esa funcin directamente.
 *
 *      SETGET       Para datos calculados. El nombre del mtodo puede ser
 *                   manipulado como un elemento de DATA para establecer
 *                   (Set) u obtener (Get) un valor.
 *
 *      VIRTUAL      Mtodos que no hacen nada. Utiles para Clases de Base
 *                   donde la Clase hija definir el comportamiento del
 *                   mtodo,  cuando Ud. esta creando y probando una Clase.
 *
 *      OPERATOR     Operador de Sobrecarga para las Clases.
 *                   Vea el ejemplo ../Tests/TestOp.prg para detalles
 *
 *      CLASS <ClassName>
 *                   Use esta sintaxis solamente para definir un mtodo
 *                   completo despus del comando ENDCLASS.
 *  $EXAMPLES$
 *      <fixed>
 *      CLASS TWindow
 *         DATA   hWnd, nOldProc
 *         METHOD New( ) CONSTRUCTOR
 *         METHOD Capture() INLINE  SetCapture( ::hWnd )
 *         METHOD End() BLOCK  { | Self, lEnd | If( lEnd := ::lValid(),;
 *                                 ::PostMsg( WM_CLOSE ),), lEnd }
 *         METHOD EraseBkGnd( hDC )
 *         METHOD cTitle( cNewTitle ) SETGET
 *         METHOD Close() VIRTUAL
 *      ENDCLASS
 *
 *      METHOD New( ) CLASS TWindow
 *         local nVar, cStr
 *         ... <codigo> ...
 *         ... <codigo> ...
 *      RETURN Self
 *      </fixed>
 *  $TESTS$
 *      <fixed>
 *      TestOp.prg
 *      </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      METHOD es una extensin de Harbour.
 *  $PLATFORMS$
 *      Todas
 *  $SEEALSO$
 *      HBClass(),Programacion Orientada a Objeto,DATA,CLASS
 *  $END$
 */

/*  $DOC$
 *  $COMMANDNAME$
 *      MESSAGE
 *  $CATEGORY$
 *      Comando OOP
 *  $ONELINER$
 *      Reenva la llamada de un mtodo a otro mtodo.
 *  $SYNTAX$
 *      MESSAGE <NombreMensaje>   METHOD <NombreMtodo>( [<params,...>] )
 *      MESSAGE <NombreMensaje>() METHOD <NombreMtodo>( [<params,...>] )
 *  $ARGUMENTS$
 *      <NombreMensaje>  El nombre del pseudo-mtodo a definir.
 *
 *      <NombreMtodo>   El mtodo a crear y llamar cuando <NombreMensaje>
 *                       es invocado.
 *      <params,...>     Lista de parmetros opcionales para el mtodo
 *  $DESCRIPTION$
 *      El comando MESSAGE es una caracterstica rara vez usada, que permite
 *      re-enviar una llamada a un mtodo con un nombre diferente. Esto puede
 *      ser necesario si el nombre de un mtodo entra en conflicto con una
 *      funcin pblica que necesita ser llamada desde adentro de un mtodo
 *      de la Clase.
 *
 *      Por ejemplo, se puede tener una funcin pblica llamda BeginPaint()
 *      que es usada para pintar las ventanas. Podra ser natural tambin
 *      tener un mtodo de la Clase Ventana, llamado :BeginPaint() que la
 *      aplicacin pueda llamar.
 *      Pero dentro del mtodo de la Clase uno podra no estar habilitado
 *      para llamar a la funcin pblica porque, los mtodos internos estn
 *      basados en funciones estticas (las que ocultan funciones pblicas
 *      con el mismo nombre)
 *
 *      El comando MESSAGE permite crear el verdadero mtodo con un nombre
 *      diferente (::xBeginPaint()) y an permitir la sintaxis ::BeginPaint()
 *      para llamar a ::xBeginPaint(). Este entonces es libre de llamar a
 *      la funcin publica BeginPaint().
 *  $EXAMPLES$
 *      <fixed>
 *      CLASS TWindow
 *         DATA   hWnd, nOldProc
 *         METHOD New( )  CONSTRUCTOR
 *         MESSAGE BeginPaint METHOD xBeginPaint()
 *      ENDCLASS
 *      </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      MESSAGE es una extensin de Harbour.
 *  $PLATFORMS$
 *      Todas
 *  $SEEALSO$
 *      METHOD,DATA,CLASS,Programacion Orientada a Objeto
 *  $END$
 */

/*  $DOC$
 *  $COMMANDNAME$
 *      ERROR HANDLER
 *  $CATEGORY$
 *      Comando OOP
 *  $ONELINER$
 *      Designa un mtodo como manejador de error para la Clase.
 *  $SYNTAX$
 *      ERROR HANDLER <NombreMtodo>( [<params,...>] )
 *  $ARGUMENTS$
 *      <NombreMtodo>  Nombre del mtodo a definir
 *
 *      <params,...>    Lista de parametros opcionales
 *  $DESCRIPTION$
 *      ERROR HANDLER nombra al mtodo que deberia manejar los errores para
 *      la Clase que esta siendo definida.
 *  $EXAMPLES$
 *      <fixed>
 *      CLASS TWindow
 *         ERROR HANDLER  MyErrHandler()
 *      ENDCLASS
 *      </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      ERROR HANDLER es una extensin de Harbour.
 *  $PLATFORMS$
 *      Todas
 *  $SEEALSO$
 *      Programacion Orientada a Objeto,ON ERROR,CLASS,METHOD,DATA
 *  $END$
 */

/*  $DOC$
 *  $COMMANDNAME$
 *      ON ERROR
 *  $CATEGORY$
 *      Comando OOP
 *  $ONELINER$
 *      Designa un mtodo como manejador de error para la Clase.
 *  $SYNTAX$
 *      ON ERROR <NombreMtodo>( [<params,...>] )
 *  $ARGUMENTS$
 *      <NombreMtodo>  Nombre del mtodo a definir
 *
 *      <params,...>    Lista de parametros opcionales
 *  $DESCRIPTION$
 *      ON ERROR es un sinnimo para ERROR HANDLER.
 *      Este nombra al mtodo que debera manejar los errores para la
 *      Clase que esta siendo definida.
 *  $EXAMPLES$
 *      <fixed>
 *      CLASS TWindow
 *         ON ERROR  MyErrHandler()
 *      ENDCLASS
 *      </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      ON ERROR es una extensin de Harbour.
 *  $PLATFORMS$
 *      Todas
 *  $SEEALSO$
 *      Programacion Orientada a Objeto,ERROR HANDLER,CLASS,METHOD,DATA
 *  $END$
 */

/*  $DOC$
 *  $COMMANDNAME$
 *      ENDCLASS
 *  $CATEGORY$
 *      Comando OOP
 *  $ONELINER$
 *      Termina la declaracin de una Clase.
 *  $SYNTAX$
 *      ENDCLASS
 *  $DESCRIPTION$
 *      ENDCLASS marca el fin de la declaracin de una Clase.
 *      Este es usualmente seguido por el mtodo de la Clase que no es
 *      INLINE.
 *  $EXAMPLES$
 *      <fixed>
 *      CLASS TWindow
 *         DATA   hWnd, nOldProc
 *      ENDCLASS
 *      </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      ON ERROR es una extensin de Harbour.
 *  $PLATFORMS$
 *      Todas
 *  $SEEALSO$
 *      Programacion Orientada a Objeto,CLASS,METHOD,DATA
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      Programacion Orientada a Objeto
 *  $CATEGORY$
 *      Documento
 *  $ONELINER$
 *      Programacion Orientada a Objeto
 *  $DESCRIPTION$
 *      </b>Programacin Orientada a Objeto (OOP)</b>
 *
 *      <b>INTRODUCCION</b>
 *
 *      Esta es una breve introducin al mundo OOP, no pretende ser ms que
 *      un ayuda memoria de algunos puntos.
 *      El Objetivo de la OOP de Harbour es alcanzar la mxima compatibilidad
 *      posible con otros programas que provean de funcionalidad OOP a
 *      Clipper donde este no la tenia.
 *      Algunos de ellos son Class(y), FiveWin Objects, TopClass y Visual
 *      Object.
 *
 *
 *      <b>OBJETOS</b>
 *
 *      Tradicionalmente la implementacin de objetos, ha sido basado en
 *      lo que se conoce como "estructuras", un tipo de datos habitual en
 *      lenguaje "C" (struct) y (record) en Pascal y Delphi.
 *      Tanto en Clipper como en Harbour los objetos se implementan sobre
 *      arrays.
 *      Un objeto puede contener a la vez variables y funciones.
 *      Mientras ese objeto-array se conserve se puede pasar como parmetro
 *      modificarlo, ejecutar las funciones contenidas en l, etc.
 *      Uno vive rodeado de objetos. Podemos considerar Arbol como una clase
 *      particular de objeto. Entonces podremos tener Pino, Roble, Acacia
 *      todos ellos son instancias de Arbol. En otras palabras ellos son
 *      objetos de la clase Arbol.
 *
 *
 *      <b>CLASE</b>
 *
 *      Es un trmino que describe una especificacin para un conjunto de
 *      objetos con propiedades comunes.
 *      Desde el punto de vista de la programacin Ud. define que debe
 *      tener una clase para que le sea til a Ud., qu atributos satisfacen
 *      sus necesidades.
 *      Esto es llamado <b>Abstraccin de datos</b> en la jerga de OOP, 
 *      Programacion Orientada a Objetos porque Ud. solamente abstrae los
 *      atributos que Ud. desea usar, de un montn de posibilidades para un
 *      objeto modelo.
 *
 *
 *      <b>INSTANCIA</b>
 *
 *      Una instancia de una clase es un trmino tcnico para un objeto de
 *      esa clase.
 *
 *
 *      <b>CLASES DE OBJETOS</b>
 *
 *      Una definicion de una clase lista todos los parametros que se
 *      necesitan para definir un objeto de esa clase en particular.
 *      La cantidad de datos necesarios para definir una clase depende
 *      de que es lo que Ud. vaya a hacer con ese objeto, pero siempre
 *      habr un mnimo que impida que una clase sea ambigua  incompleta.
 *
 *      La clase Arbol por ejemplo podra contener dos parametros en la
 *      definicin. El nombre del Arbol como cadena de caracteres, Si es
 *      perenne (si conserva las hojas en invierno) como una variable logica
 *      Los parametros que definen un objeto son denominados <b>variables</b>
 *      <b>de instancia  atributos</b> de una clase.
 *      Las variables de instancia pueden ser tipos basicos de datos como
 *      CHARACTER, NUMERIC  LOGIC, aunque tambien puede ser otros objetos
 *      como la Hoja y definida esta como de la Clase Hoja.
 *
 *
 *      <b>OPERANDO CON OBJETOS</b>
 *
 *      Una de las limitaciones basicas sobre que puede hacer con los
 *      objetos dependen del tipo de datos sobre los cuales estan basados
 *      as por ejmplo Ud. no puede hacer operaciones matematicas con el
 *      atributo <cNombre> de la clase Arbol, pero s puede compararlo con
 *      otro, etc.
 *      Las unicas operaciones que se pueden hacer sobre una instancia de una
 *      clase particular son aquellas definidas dentro de la clase.
 *      Por lo tanto, la utilidad y flexibilidad de una clase depende de
 *      cuanto esfuerzo e ingenio haya puesto al establecer su definicin.
 *      Estas operaciones se llaman <b>METODOS</b> en la jerga OOP que no son
 *      ni ms ni menos que nuestros conocidos procedimientos y funciones.
 *
 *
 *      <b>ENCAPSULAMIENTO</b>
 *
 *      Se refiere al hecho de ocultar items de datos y metodos dentro de
 *      una clase al declararlos como <b>Private</b> en la definicin de la
 *      clase. Esto protege las partes internas de la clase de ser cambiadas
 *       usadas incorrectamente.
 *      Esta habilidad de ocultar la <b>Implementacin de la clase</b>
 *      permitiendo un acceso limitado a los miembros de una clase, le da la
 *      posibilidad de cambiar las partes internas de esa clase cuando sea
 *      necesario. Mientras las caracteristicas de los metodos que pueden ser
 *      llamados desde afuera permanezcan sin cambios, la codificacin
 *      interna puede ser cambiada como se desee.
 *
 *
 *      <b>HERENCIA</b>
 *
 *      Muchos de los objetos que se definen en una clase pueden ser
 *      subdivididos en conjuntos ms especializados que tambin pueden ser
 *      representados por clases.
 *      En nuestro ejemplo de la clase Arbol, Conifera podra ser una
 *      subclase de la clase Arbol, esta podra tener todas las variables de
 *      instancia y mtodos de la clase Arbol, ms algunas variables de
 *      instancia adicionales y metodos que la definan como Conifera.
 *      Podemos referirnos a la clase conifera como una <b>Subclase</b> de
 *      la clase Arbol y a la clase Arbol como una <b>Superclase</b> 
 *      <b>Clase Padre</b> de la clase Conifera.
 *
 *
 *      <b>POLIMORFISMO</b>
 *
 *      Es la habilidad de asumir diferentes formas  contornos.
 *      Practicamente significa la habilidad de una nica variable de llamar
 *      a diferentes mtodos, dependiendo de lo que contiene la variable.
 *      El polimorfismo involucra dos cosas:
 *      1) Usar una variable de un tipo especifico, gralmente una variable
 *         de una clase base, para almacenar objetos de alguna de las clases
 *         derivadas.
 *      2) El uso automatico del objeto almacenado en la variable de la clase
 *         base para seleccionar un mtodo de entre todos los mtodos de las
 *         clases derivadas.
 *         El tipo del objeto almacenado no es conocido hasta que el
 *         programa se ejecuta, por tanto la eleccin de cual mtodo de clase
 *         a ejecutar es hecha dinamicamente.
 *
 *
 *      <b>ATRIBUTOS</b>
 *
 *      Los atributos de un objeto, a menudo son llamados <b>Miembros de</b>
 *      <b>Clase</b> y se declaran utilizando la palabra clave DATA.
 *      Por ejemplo:
 *      DATA cFile  INIT "*.txt"
 *      En Harbour se utiliza la clausula INIT para inicializar las variables
 *
 *
 *      <b>CONSTRUCTOR</b>
 *
 *      Declarar una variable para soportar un objeto no crea al objeto en
 *      s mismo, la variable solo mantiene una referencia al objeto.
 *      para crear un objeto se debe usar la palabra clave <b>New</b>.
 *      Este es seguido por una lista de argumentos opcionales entre
 *      parentesis y luego por el objeto de la clase a la que pertenecen.
 *
 *      Un constructor es la funcin que crea al objeto e inicializa las
 *      variables. Como las funciones en el lenguaje OOP se llaman
 *      mtodos el constuctor siempre se declara como  METHOD New(..)
 *
 *      METHOD New( cFile ) CLASS TNortonGuide
 *
 *         IF VALTYPE( cFile ) <> NIL .AND. VALTYPE( cFile ) == "C"
 *            Self:cFile   := LOWER( cFile )
 *            Self:nHandle := FCREATE( Self:cFile )
 *         ENDIF
 *
 *      RETURN Self
 *
 *      Cuando se crea un objeto, el objeto contendr todas las variables que
 *      fueron incluidas en la definicin de la clase. Sin embargo no todas
 *      las variables son iguales. Hay dos tipos:
 *      Un tipo de variable de clase que es asociada con cada objeto
 *      univocamente, cada instancia de la clase tendr su propia copia de
 *      estas variables con su propio valor asignado. Estas diferencian un
 *      objeto de otro, dndole a un objeto su individualidad por ello se
 *      llaman <b>Variables de Instancia</b>.
 *
 *      El otro tipo de variable de clase es asociada con la clase y es
 *      compartida con todos los objetos de la clase. Hay solo una copia
 *      de este tipo de variables, no importa cuantos objetos sean creados.
 *      Este ltimo tipo se llama <b>Variables de Clase</b>, ellas existen
 *      an si ningn objeto de esta clase ha sido creado. Ellas pertenecen
 *      a la clase, pero son incluidas como parte de cada objeto de la clase.
 *      Si el valor de una variable de clase es cambiado, el nuevo valor est
 *      disponible en todos los objetos de la clase.
 *      Una variable de clase debe ser definida usando la palabra clave
 *      CLASSDATA (es equivalente a STATIC en el mundo OOP) precediendo a su
 *      nombre.
 *
 *      Al igual que con las variables existen dos tipos de Mtodos:
 *      <b>Metodos de Clase</b> Ud. puede ejecutar Metodos de Clase, an
 *      si ningn objeto de esta clase ha sido creado. Al igual que con las
 *      variables de clase son precedidos del identificador STATIC en la
 *      mayoria de los lenguajes OOP.
 *
 *      Mientras que los <b>Metodos de Instancia</b> solamente pueden ser
 *      ejecutados en relacin a un objeto particular, as que si no existe
 *      el objeto, NO hay mtodo de instancia a ser ejecutado.
 *
 *      Debe tenerse en cuenta que no se puede hacer referencia a ninguna
 *      variable de instancia dentro de una clase dentro un mtodo Static
 *      Estto se debe a que su mtodo Static puede ser ejecutado cuando
 *      todava ningn objeto de la clase a sido creado y por lo tanto NO
 *      existen variables de instancia.
 *
 *
 *      <b>SELF</b>
 *
 *      Habitualmente los mtodos de una clase, devuelven una referencia al
 *      objeto sobre el cual actan y esa referencia se denomina <Self>
 *
 *
 *      <b>DEFINIENDO UNA CLASE</b>
 *
 *      Una clase se define con la palabra clave CLASS seguida de un nombre
 *      que identifica a la clase. Para indicar que termina una clase se
 *      utiliza la palabra clave ENDCLASS
 *      Por tradicin, las clases en Harbour comienzan con la letra "T"
 *      (algo comn en el mundo OOP) para evitar colisiones con clases
 *      creadas por el usuario.
 *
 *      la por ej.
 *      METHOD <NombreMtodo>( [<params,...>] ) CLASS <NombreClase>
 *
 *      Los Mtodos pueden referenciar al objeto actual usando la palabra
 *      clave "Self:"  su versin ms corta "::"
 *      Vea METHOD para una explicacin de las distintas variantes.
 *
 *
 *      <b>VIDA DE UN OBJETO</b>
 *
 *      La vida de un objeto esta determinada por la variable que hace
 *      referencia a l. Si distintas variables hacen referencia a un
 *      mismo objeto, el objeto sobrevive mientras todava haya una variable
 *      que haga referencia a ese objeto.
 *      Si creamos un objeto
 *          oNgi := TNortonGuide():new( "Myfile" )
 *      y luego hacemos
 *          oNgi := NIL
 *      la variable oNgi no apunta ms al objeto, se pierde la referencia y
 *      si asumimos que no hay ninguna otra variable referenciandolo entonces
 *      el objeto TNortonGuide al cual ella apunta queda disponible para el
 *      el recolector de memoria.
 *      Pero el objeto no desaparece instantneamente, sino que pasa algn
 *      tiempo hasta que el objeto se vuelve inaccesible para su programa
 *      (cuando el subsistema de memoria dispone de tiempo de procesamiento),
 *      se ocupa de l.
 *
 *
 *      <b>SOBRECARGA</b>
 *      Vea testop.prg por un ejemplo
 *
 *
 *      <b>CLONANDO OBJETOS</b>
 *      Algunos lenguajes OOP proveen una mtodo preconstruido para duplicar
 *      objetos.
 *
 *      <b>Comentario Final</b>
 *
 *      Los programas Orientados a Objetos son escritos usando objetos los
 *      cuales modelan el problema que esta siendo resuelto.
 *      Debido a que un objeto incluye los mtodos con los cuales puede
 *      operar, as como los datos que lo definen, este tipo de programacin
 *      es menos propensa a errores (segn los especialistas) y debera ser
 *      ms robusta que la forma de programacin procedural.
 *
 *      Estas caractersticas son las que han facilitado la proliferacin de
 *      lenguajes como Java y Python. Pero una de las desventajas ms notables
 *      es la dificultad muchas veces para intercambiar la informacin
 *      almacenada en esos objetos con otros programas y la conservacin de
 *      esos objetos en un medio magnetico (<b>Serializacin</b>) en un
 *      formato compatible, algo que segn los expertos promete XML y que ya
 *      est disponible con Harbour.
 *
 *  $EXAMPLES$
 *      CLASS Circle
 *
 *      CLASS TNortonGuide
 *
 *         DATA cFile                // Nombre archivo
 *         DATA nHandle              // file handle
 *         METHOD New( cFile )       // constructor, funcion que crea archivo
 *         METHOD CLOSE()            // funcion que cierra archivo
 *         METHOD WriteParBold( cPar )
 *         METHOD WriteTitle( cTopic, cTitle )
 *
 *      ENDCLASS
 *
 *      METHOD new( cFile ) CLASS TNortonGuide
 *
 *         IF VALTYPE( cFile ) <> NIL .AND. VALTYPE( cFile ) == "C"
 *            Self:cFile   := LOWER( cFile )
 *            Self:nHandle := FCREATE( Self:cFile )
 *         ENDIF
 *
 *      RETURN Self
 *
 *
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      La sintaxis Orientada a Objetos en Harbour es compatible con
 *      CA-Cl*pper.
 *      Pero Clipper solamente permite la creacin de objetos a partir
 *      de unas pocas clases estandares, y NO le permite al programador
 *      crear nuevas clases.
 *      En Harbour, Ud. puede crear sus propias clases completamente con
 *      Mtodos, Variables de Instancia, Variables de Clase y Herencia.
 *      Aplicaciones enteras pueden ser designadas y codificadas en el
 *      estilo Orientado a Objetos.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *  $SEEALSO$
 *      __objHasData(),CLASS,METHOD
 *  $END$
 */



