Tipo de Datos para el manejo de planillas Excel

Introducción

La finalidad de este nuevo tipo de datos es unificar las funciones de interacción con la generación de planillas Excel para los distintos lenguajes generados.

 

Una ventaja importante de esta implementación 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, Work Panels, Web Panels, Procedimientos, Reportes

Lenguajes: Java, Visual Basic , Visual FoxPro

Interface: Win

 

Descripción

Para utilizar esta nueva funcionalidad se creó el tipo de datos llamado ExcelDocument que permite, a través de sus propiedades y métodos generar y manejar planillas de Microsoft Excel.

 

Además 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 métodos disponibles para este tipo de datos son los siguientes:

 

Propiedad

Tipo

Acceso

Bold

Numérico

Lectura/Escritura

Color

Numérico

Lectura/Escritura

Date

DateTime

Lectura/Escritura

Font

Carácter

Lectura/Escritura

Italic

Numérico

Lectura/Escritura

Number

Numérico

Lectura/Escritura

Size

Numérico

Lectura/Escritura

Text

Carácter

Lectura/Escritura

Type

Carácter

Lectura

Underline

Numérico

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 están 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 número de color en el esquema RGB (es decir, como un valor retornado por la función 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 vacía.

 

Italic

Especifica si las celdas se muestran en itálica (1) o no (0).

 

Sintaxis:            &ExcelDocument.Cells(…).Italic

 

La propiedad Italic solamente devolverá valor 1 si todas las celdas en el objeto ExcelCells están en itálica. En caso contrario devolverá 0.

 

Number

Valor de las celdas en formato numérico.

 

Sintaxis:            &ExcelDocument.Cells(…).Number

 

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

 

Size

Especifica el tamaño 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 tamaños 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 vacía.

 

Type

Devuelve el tipo del valor de una celda determinada.

 

Sintaxis:            &ExcelDocument.Cells(…).Type

 

La propiedad Type tendrá uno de los siguientes valores:

·         “D”        si el tipo es fecha o fecha/hora.

 

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 están subrayadas. En caso contrarió devolverá 0.

 

 

ExcelDocument

Las propiedades y métodos disponibles para este tipo de datos son los siguientes:

 

Propiedad

Tipo

Acceso

AutoFit

Numérico

Lectura/Escritura

Delimiter

Carácter

Lectura/Escritura

ErrCode

Numérico

Lectura

ErrDescription

Carácter

Lectura

ErrDisplay

Numérico

Lectura/Escritura

MacroReturnText

Carácter

Lectura

MacroReturnNumber

Numérico

Lectura

MacroReturnDate

Fecha

Lectura

ReadOnly

Numérico

Lectura/Escritura

Template

Carácter

Lectura/Escritura

 

 

Método

Parámetros

Tipo

Cells

Row

Column

Height

Width

Numérico

Numérico

Numérico

Numérico

Clear

(ninguno)

 

Close

(ninguno)

 

Hide

(ninguno)

 

Open

FileName

Carácter

Print

Preview

Numérico

RenameSheet

SheetName

Carácter

RunMacro

MacroName

Par1 … Par30

Carácter

(Cualquiera)

Save

(ninguno)

 

SelectSheet

SheetName

Carácter

Show

(ninguno)

 

Unbind

(ninguno)

Numérico

 

Propiedades

AutoFit

Ajustar automáticamente o no el ancho de las columnas.

 

Sintaxis:            &ExcelDocument.AutoFit

 

Especifica si se ajustará automáticamente (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 automático 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

Código de error de la última operación.

 

Sintaxis:            &ExcelDocument.ErrCode

 

Ver sección “Códigos y Mensajes de Error”.

 

ErrDescription

Mensaje de error de la última operación.

 

Sintaxis:            &ExcelDocument.ErrDescription

 

Ver sección “Códigos 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 carácter devuelto por un llamado a una macro mediante el método RunMacro.

 

Sintaxis:            &WordDocument.MacroReturnText

 

Nota:

-          Esta propiedad no está disponible para el generador Java.

 

MacroReturnNumber

Ultimo valor numérico devuelto por un llamado a una macro mediante el método 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 método RunMacro.

 

Sintaxis:            &WordDocument.MacroReturnDate

 

Nota:

-          Esta propiedad no está disponible para el generador Java.

 

ReadOnly

Abrir el próximo documento como sólo lectura.

 

Sintaxis:            &ExcelDocument.ReadOnly

 

Si ReadOnly es 1, la próximas llamadas al método Open causarán que las planillas se abran como sólo lectura.

Si es 0 se intentarán abrir como lectura/escritura, pero si ya se encuentran abiertas se abrirán como sólo 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 próximas llamadas al método Open con un nombre de archivo no existente.

El valor por defecto es la cadena vacía. 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 vacío, 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 parámetro un string vacío (“”).

 

 

Métodos

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 parámetros Height y 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 método Open, éste no es desplegado en pantalla. Para mostrarlo es necesario llamar al método Show.

 

Print

Imprime el documento en la impresora por defecto.

 

Sintaxis:            &ExcelDocument.Print([Preview])

 

El parámetro 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 método se debe configurar la preferencia “Functions = Allow non standard functions” en diseño y prototipo.

 

RenameSheet

Renombra la hoja activa al nombre especificado.

 

Sintaxis:            &ExcelDocument.RenameSheet(SheetName)

 

RunMacro

Ejecuta una macro contenida en el documento con los parámetros que se especifiquen.

 

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

 

Notas:

·         Los parámetros son sólo de entrada. Si la macro llamada devuelve valores, éstos quedarán almacenado en las propiedades MacroReturnText, MacroReturnNumber y MacroReturnDate, dependiendo de su tipo.

·         Hay un máximo de 30 parámetros, esto es una limitación de Word.

·         Esta función no está disponible para el generador Java.

·         Si se utiliza este método con Office 97, no es posible utilizar parámetros, esto es una limitación de Office 97. Por esta razón tampoco es posible invocar las propiedades MacroReturnText, MacroReturnNumber y MacroReturnDate en este caso.

 

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 aplicación.

 

Sintaxis:            &ExcelDocument.Unbind()

 

Este método 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 aplicación.

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 más al documento. De hecho, el objeto ExcelDocument se comporta como si no tuviera un documento abierto hasta que no se llame nuevamanete al método Open.

 

 

Códigos y Mensajes de Error

Los valores posibles son:

 

Código

Mensaje

0

Ok

2

Workbook no longer valid  (sucede cuando un libro que fue abierto desde un programa es cerrado a mano por el usuario).

3

Application no longer valid (sucede cuando Excel es cerrado a mano por el usuario).

4

Invalid template

5

Invalid worksheet name

6

Invalid font properties

7

Invalid cell value

8

Invalid cell coordinates

9

Invalid file name

10

Could not open file

11

Error running macro

12

Could not save file

 

 

Consideraciones Generales

-          Los métodos descritos anteriormente fueron implementados de forma tal que devuelven (como si fueran funciones) el código 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 existían hasta la versión 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 serán implementadas en dichas funciones.

Ejemplos

Puede obtener un ejemplo en esta URL:

http://www.gxopen.com.uy/hproject.asp?127