Tipo de Datos para el manejo de planillas Excel

Introduccin
La finalidad de este nuevo tipo de datos es unificar las funciones de interaccin con la generacin de planillas Excel para los distintos lenguajes generados.

Una ventaja importante de esta implementacin con respecto a las anteriores, es que se manejan las planillas con un modelo orientado a objetos. No hay que llevar control de los manejadores de los documentos (Handles).

Alcance
Objetos: Transacciones, WorkPanels, Web Panels, Procedimientos, Reportes Lenguajes: Java, Visual Basic , Visual FoxPro Interface: Win

Descripcin
Para utilizar esta nueva funcionalidad se cre el tipo de datos llamado ExcelDocument que permite, a travs de sus propiedades y mtodos generar y manejar planillas de Microsoft Excel.

Adems internamente se implementa el tipo de datos ExcelCells, que se utiliza para manejar al conjunto de celdas que existen en la planilla.

ExcelCells
Las propiedades y mtodos disponibles para este tipo de datos son los siguientes:

Propiedad Bold Color Date Font Italic Number Size Text Type Underline

Tipo Numrico Numrico DateTime Carcter Numrico Numrico Numrico Carcter Carcter Numrico

Acceso Lectura/Escritura Lectura/Escritura Lectura/Escritura Lectura/Escritura Lectura/Escritura Lectura/Escritura Lectura/Escritura Lectura/Escritura Lectura Lectura/Escritura

PROPIEDADES
Bold

Especifica si las celdas se muestran en negrita (1) o no (0).

Sintaxis:

&ExcelDocument.Cells().Bold

Esta propiedad solamente devolver 1 si todas las celdas en el objeto ExcelCells estn en negrita. En caso contrario devolver 0.

Color

Especifica el color de las celdas.

Sintaxis:

&ExcelDocument.Cells().Color

Si se especifica un valor positivo se tomar dicho valor como ndice de color de Excel. En cambio, si se especifica un valor negativo (excepto 1), se tomar su valor absoluto como nmero de color en el esquema RGB (es decir, como un valor retornado por la funcin RGB). Si se especifica el valor 1, se toma el color por defecto definido en Excel.

Si existen celdas en el objeto ExcelCells con distintos colores, esta propiedad devolver 0.

Date

Valor de las celdas en formato de fecha y hora.

Sintaxis:

&ExcelDocument.Cells().Date

Si existen celdas en el objeto ExcelCells con distintos valores, la propiedad Date devolver la fecha nula.

Font

Especifica la fuente utilizada para desplegar el valor de las celdas.

Sintaxis:

&ExcelDocument.Cells().Font

Si existen celdas en el objeto ExcelCells que utilizan distintas fuentes, la propiedad Font devolver la cadena vaca.

Italic

Especifica si las celdas se muestran en itlica (1) o no (0).

Sintaxis:

&ExcelDocument.Cells().Italic

La propiedad Italic solamente devolver valor 1 si todas las celdas en el objeto ExcelCells estn en itlica. En caso contrario devolver 0.

Number

Valor de las celdas en formato numrico.

Sintaxis:

&ExcelDocument.Cells().Number

Si existen celdas en el objeto ExcelCells con distintos valores, la propiedad Number devolver cero.

Size

Especifica el tamao de la fuente utilizada para desplegar el valor de las celdas.

Sintaxis:

&ExcelDocument.Cells().Size

Si existen celdas en el objeto ExcelCells que utilizan distintos tamaos fuentes, la propiedad Size devolver 0.

Text

Valor de las celdas en formato de texto.

Sintaxis:

&ExcelDocument.Cells().Text

Si existen celdas en el objeto ExcelCells con distintos valores, la propiedad Text devolver la cadena vaca.

Type

Devuelve el tipo del valor de una celda determinada.

Sintaxis:

&ExcelDocument.Cells().Type

La propiedad Type tendr uno de los siguientes valores:

y y

N C D U

si el tipo es numrico. si el tipo es carcter. si el tipo es fecha o fecha/hora. si el tipo es desconocido.

y
y

Si existen celdas en el objeto ExcelCells que contienen distintos tipos, la propiedad Type devolver U.

Underline

Especifica si las celdas se muestran subrayadas (1) o no (0).

Sintaxis:

&ExcelDocument.Cells().Underline

La propiedad Underline solamente devolver valor 1 si todas las celdas en el objeto ExcelCells estn subrayadas. En caso contrari devolver 0.

ExcelDocument
Las propiedades y mtodos disponibles para este tipo de datos son los siguientes:

Propiedad AutoFit Delimiter ErrCode ErrDescription ErrDisplay MacroReturnText MacroReturnNumber MacroReturnDate

Tipo Numrico Carcter Numrico Carcter Numrico Carcter Numrico Fecha

Acceso Lectura/Escritura Lectura/Escritura Lectura Lectura Lectura/Escritura Lectura Lectura Lectura

ReadOnly Template

Numrico Carcter

Lectura/Escritura Lectura/Escritura

Mtodo Cells Row

Parmetros

Tipo Numrico Numrico Numrico Numrico

Column Height Width (ninguno) (ninguno) (ninguno) FileName Preview SheetName MacroName Par1 Par30 (ninguno) SheetName (ninguno) (ninguno)

Clear Close Hide Open Print RenameSheet RunMacro

Carcter Numrico Carcter Carcter (Cualquiera) Carcter Numrico

Save SelectSheet Show Unbind

PROPIEDADES
AutoFit

Ajustar automticamente o no el ancho de las columnas.

Sintaxis:

&ExcelDocument.AutoFit

Especifica si se ajustar automticamente (1) o no (0) el ancho de las columnas al modificar cualquiera de las propiedades de una celda o un grupo de ellas. El ajuste automtico se har de manera tal que quede visible todo el contenido de las celdas modificadas. El valor por defecto es 0.

Delimiter

Separador de campos a utilizar al abrir archivos de texto.

Sintaxis:

&ExcelDocument.Delimiter

El valor por defecto es la coma (,).

ErrCode

Cdigo de error de la ltima operacin.

Sintaxis:

&ExcelDocument.ErrCode

Ver seccin Cdigos y Mensajes de Error.

ErrDescription

Mensaje de error de la ltima operacin.

Sintaxis:

&ExcelDocument.ErrDescription

Ver seccin Cdigos y Mensajes de Error.

ErrDisplay

Desplegar o no mensajes de error.

Sintaxis:

&ExcelDocument.ErrDisplay

Especifica si al ocurrir un error se desplegar un mensaje advirtiendo al usuario con el texto del error (1) o no (0). El valor por defecto es 0.

MacroReturnText

Ultimo valor de tipo carcter devuelto por un llamado a una macro mediante el mtodo RunMacro.

Sintaxis:

&WordDocument.MacroReturnText

Nota: Esta propiedad no est disponible para el generador Java.

MacroReturnNumber

Ultimo valor numrico devuelto por un llamado a una macro mediante el mtodo RunMacro.

Sintaxis:

&WordDocument.MacroReturnNumber

Nota: Esta propiedad no est disponible para el generador Java.

MacroReturnDate

Ultimo valor de tipo fecha devuelto por un llamado a una macro mediante el mtodo RunMacro.

Sintaxis:

&WordDocument.MacroReturnDate

Nota: Esta propiedad no est disponible para el generador Java.

ReadOnly

Abrir el prximo documento como slo lectura.

Sintaxis:

&ExcelDocument.ReadOnly

Si ReadOnly es 1, la prximas llamadas al mtodo Open causarn que las planillas se abran como slo lectura. Si es 0 se intentarn abrir como lectura/escritura, pero si ya se encuentran abiertas se abrirn como slo lectura. El valor por defecto es 0.

Template

Nombre del template a utilizar para documentos nuevos.

Sintaxis:

&ExcelDocument.Template

Indica el camino y el nombre del archivo que se que se utilizar como Template en las prximas llamadas al mtodo Open con un nombre de archivo no existente. El valor por defecto es la cadena vaca. En este caso se utilizar el template por defecto.

El tipo de archivo puede ser cualquiera permitido por Excel para utilizarlo como Template. Si es el string vaco, se usar el template por defecto. Por defecto, no hay template asignado y por lo tanto se utiliza el template por defecto.

Si se define un template, y luego se borra porque ya no se necesita, para volver a utilizar el template por defecto se debe hacer una llamada a esta propiedad, pasando por parmetro un string vaco ().

MTODOS
Cells

Devuelve una celda o un conjunto de celdas.

Sintaxis:

&ExcelDocument.Cells(Row, Column[, Height, Width])

Devuelve un objeto ExcelCells con las celdas que componen el rea que comienza en la fila Row y columna Column y tiene Height celdas de alto y Width celdas de ancho. Si no se especifican los parmetros Heighty Width se devolver solamente la celda ubicada en la fila Row y columna Column

Clear

Borra el contenido y el formato de todas las celdas de la hoja activa.

Sintaxis:

&ExcelDocument.Clear()

Close

Salva y cierra el documento.

Sintaxis:

&ExcelDocument.Close()

Hide

Oculta el documento.

Sintaxis:

&ExcelDocument.Hide()

Open

Abre el documento especificado.

Sintaxis:

&ExcelDocument.Open(FileName)

De no existir el documento especificado, ste se crea utilizando el template especificado en la propiedad Template. Al abrir un documento mediante el mtodo Open, ste no es desplegado en pantalla. Para mostrarlo es necesario llamar al mtodo Show.

Print

Imprime el documento en la impresora por defecto.

Sintaxis:

&ExcelDocument.Print([Preview])

El parmetro Preview indica si se mostrar el documento por pantalla (1) o no (0) antes de imprimirlo. El valor por defecto es 0.

Nota: Para poder utilizar este mtodo se debe configurar la preferencia Functions = Allow non standardfunctions en diseo y prototipo.

RenameSheet

Renombra la hoja activa al nombre especificado.

Sintaxis:

&ExcelDocument.RenameSheet(SheetName)

RunMacro

Ejecuta una macro contenida en el documento con los parmetros que se especifiquen.

Sintaxis:

&ExcelDocument.RunMacro(MacroName[, Par1 ... [,Par30]])

Notas:
y

Los parmetros son slo de entrada. Si la macro llamada devuelve valores, stos quedarn almacenado en las propiedades MacroReturnText, MacroReturnNumber y MacroReturnDate, dependiendo de su tipo. Hay un mximo de 30 parmetros, esto es una limitacin de Word. Esta funcin no est disponible para el generador Java. Si se utiliza este mtodo con Office 97, no es posible utilizar parmetros, esto es una limitacin de Office 97. Por esta razn tampoco es posible invocar las propiedades MacroReturnText, MacroReturnNumber y MacroReturnDate en este caso.

y y y

Save

Guarda el documento a disco.

Sintaxis:

&ExcelDocument.Save()

SelectSheet

Cambia la hoja activa a la especificada.

Sintaxis:

&ExcelDocument.SelectSheet(SheetName)

De no existir la hoja especificada, se crea.

Show

Muestra el documento en pantalla.

Sintaxis:

&ExcelDocument.Show()

Unbind

Permite dejar abierta la planilla Excel, luego de finalizar la aplicacin.

Sintaxis:

&ExcelDocument.Unbind()

Este mtodo es til si se desea que una planilla permanezca abierta luego de que se pierde de alcance el objeto ExcelDocument, incluso luego de finalizada la aplicacin. Al liberar una planilla se pierde por completo la referencia entre el objeto ExcelDocument y el documento abierto. Las operaciones sobre el objeto ExcelDocument no afectan ms al documento. De hecho, el objeto ExcelDocument se comporta como si no tuviera un documento abierto hasta que no se llame nuevamanete al mtodo Open.

Cdigos y Mensajes de Error

Los valores posibles son:

Cdigo 0 2

3 4 5

Mensaje Ok Workbook no longervalid (sucede cuando un libro que fue abierto desde un programa es cerrado a mano por el usuario). Application no longervalid (sucede cuando Excel es cerrado a mano por el usuario). Invalidtemplate Invalidworksheetname

6 7 8 9 10 11 12

Invalidfontproperties Invalidcellvalue Invalidcellcoordinates Invalid file name Couldnot open file Error running macro Couldnotsave file

Consideraciones Generales
Los mtodos descritos anteriormente fueron implementados de forma tal que devuelven (como si fueran funciones) el cdigo de error, por lo que es posible llamarlos como funciones. Por ejemplo: &Err = &ExcelDocument.Open(Archivo)

Compatibilidad con versiones anteriores de GeneXus

Las funciones de GXoffice que existan hasta la versin 7.0 de GeneXs, se siguen soportando, el generador funciona de forma tal que mapea internamente estas funciones para que utilicen estos nuevos tipos de datos. Estas funciones se soportan unicamente por compatibilidad, por lo que no se recomienda hacer nuevas implementaciones con las mismas pues las nuevas funcionalidades no sern implementadas en dichas funciones.

Ejemplos
Puede obtener un ejemplo en esta URL: http://www.gxopen.com.uy/hproject.asp?127