Tema 1.5 - Microsoft Office con AutoIt

AutoIt es una herramienta tan potente que dispone de ciertas UDFs (Funciones definidas por el usuario) que nos permiten manipular archivos de Microsoft de una manera más simple.

Las funciones definidas por el usuario básicamente son código que, ya sea por su complejidad o por ser repetitivo, pueden ser encapsuladas y reusadas en varios procesos.

Actualmente AutoIt sólo tienen UDFs para los programas informáticos Microsoft Word y Microsoft Excel.

UDFs Microsoft Word

A continuación, se verán algunas funciones con las que cuenta AutoIt para el manejo de archivos de Word. Si desea encontrar la lista completa puede ingresar al siguiente enlace: Funciones Definidas Por El Usuario (UDFs).

Nota: Para utilizar las funciones de Word, usted debe incluir el archivo “Word.au3” en su script, usando la línea #include <Word.au3>.

• _Word_Create: Permite conectarse a una instancia de Word ya existente o crear un nuevo objeto de aplicación de Word si no hay ninguna ventana de Word abierta. Su sintaxis es la siguiente.

1	_Word_Create([$bVisible=True[,$bForceNew=False]])

• Los corchetes representan las partes de la sintaxis que son opcionales.
• $bVisibe, especifica si la ventana será visible. Por defecto este parámetro es True.
• $bForceNew, fuerza a crear una nueva instancia de Word incluso si ya hay una instancia en ejecución. El valor predeterminado de este parámetro de False.
• • En caso de éxito, la función retorna un apuntador hacia el objeto Word.Application y cambia el valor del macro @extended a 0 si Word ya se estaba ejecutando y 1 si el Word no se estaba ejecutando o si $bForceNew se estableció en True.

Ejemplo: Abramos un archivo de Word, luego, creemos un script con nombre WordCreate y colocamos el siguiente código.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

#include <Word.au3>

AbrirWord()

Func AbrirWord()
	_Word_Create()
	If @extended = 0 Then
		MsgBox(0,"Ejemplo WordCreate","Microsoft Word ya se está ejecutando.")
	ElseIf @extended = 1 Then
		MsgBox(0,"Ejemplo WordCreate","Microsoft Word no se estaba ejecutando.")
	EndIf
EndFunc

Al ejecutar el script se nos mostrará el primer mensaje “Microsoft Word ya se está ejecutando” debido a que ya hay una instancia de Word abierta.

Ahora cerremos el archivo de Word y volvamos a ejecutar el script, en este caso el valor de @extended será 1 por ende, mostrará el mensaje “Microsoft Word no se estaba ejecutando” y por último se abrirá un nuevo Word.

• _Word_DocAdd: Añade un nuevo documento vacío al archivo de Word. La sintaxis de esta función se muestra a continuación.

1	_Word_DocAdd($oAppl[,$iDocumentType=$WdNewBlankdDocument[,$sDocumentTemplate=""[,$bNewTemplate=False]]])

• Los corchetes representan las partes de la sintaxis que son opcionales.
• $oAppl, es un objeto de Word retornado por una llamada anterior a la función _Word_Create().
• $iDocumentType, este parámetro puede ser unas de las siguientes constantes: $WdNewBlankDocument, $WdNewEmailMessage, $WdNewFrameset o $WdNewWebPage. El valor predeterminado es $WdNewBlankDocument.
• sDocumentTemplate, nombre de la plantilla del nuevo documento de Word. Si se omite este parámetro, se coloca la plantilla normal que viene defecto (“”).
• $bNewTemplate, si este valor es True abre el documento como una plantilla. Por defecto este valor viene como False.
• La función en caso de éxito (abrir un nuevo documento de Word) retorna un apuntador hacia el nuevo objeto de documento y la macro @error tendrá un valor de 0.
• La función en caso de fallar retorna 0 (no abre un nuevo documento de Word) y cambia la macro @error a un número distinto de 0. Los valores de @error aparte de cero, puede ser alguno de estos: 1 -> Si $oAppl no es un objeto, 2 -> Si la plantilla especificada no existe, 3 ->Error retornado por el método Document.Add.

Ejemplo: Creemos un nuevo script que tendrá como nombre WordDocAdd y en ella escribimos este código.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

#include <Word.au3>

Local $oWord = _Word_Create()

_Word_DocAdd($oWord)

If @error = 0 Then
	MsgBox(0,"WordDocAdd","$oWord es un objeto de Word.")
ElseIf @error = 1 Then
	MsgBox(0,"WordDocAdd","$oWord no es un objeto de Word.")
EndIf

Al ejecutar este script nos deberá abrir simplemente un nuevo documento de Word y mostrará el mensaje “$oWord es un objeto de Word.” porque como la función tuvo éxito la macro @error tendrá un valor de 0.

Si modificamos el código anterior y le asignamos a la variable $oWord un String, la función no nos debería abrir ningún documento de Word, pero sí deberá mostrar el mensaje “$oWord no es un objeto de Word.” ya que, al haber fallado la función, la macro @error tendrá el valor de 1.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

#include <Word.au3>

Local $oWord = "Hola Mundo"

_Word_DocAdd($oWord)

If @error = 0 Then
	MsgBox(0,"WordDocAdd","$oWord es un objeto de Word.")
ElseIf @error = 1 Then
	MsgBox(0,"WordDocAdd","$oWord no es un objeto de Word.")
EndIf

• _Word_DocOpen: Esta UDF me permite abrir un documento de Word. La sintaxis es la siguiente.

1 2 3

_Word_DocOpen($oAppl,$sFilePath[,$bConfirmConversions=False [,$iFormat=WdOpenFormatAuto[,$bReadOnly=False[,$bRevert=False [,$bAddToRecentFiles=False[,$sOpenPassword=""]]]]]])

• $oAppl, es un objeto de Word devuelto por un llamado anterior a la función _Word_Create().
• $sFilePath, nombre o ruta del documento para abrir.
• $bReadOnly, si este parámetro es True abre el documento como solo lectura. El valor predeterminado es False. Este argumento no anula la configuración recomendada de solo lectura en un documento guardado.
• La función en caso de éxito (abrir el documento especificado), retorna un apuntador hacia el objeto del documento Word y la macro @error tendrá el valor de 0.
• La función en caso de no poder abrir el documento especificado establece la macro @error distinto a cero. Los posibles valores que puede tomar esta macro aparte de cero son los siguientes: 1-> Si $oAppl no es un objeto, 2 -> Si el documento especificado no existe, 3 -> Se produjo un error al abrir el documento.

Nota: La información de los otros parámetros de la función, la puede encontrar ingresando a este enlace UDF WorDocOpen.

Ejemplo: Antes de realizar nuestro script de AutoIt, creemos un nuevo documento de Word con el nombre Prueba UDF WordDocOpen, lo guardamos en nuestro escritorio y cerramos el archivo. Después de haber hecho esto, escribimos el siguiente script.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

#include <Word.au3>
#include <MsgBoxConstants.au3>

AbrirDocumentoWord()

Func AbrirDocumentoWord()
	Local $oWord = _Word_Create()
	_Word_DocOpen($oWord,@DesktopDir&"\Prueba UDF WordDocOpen.docx")
	If @error = 0 Then
		MsgBox($MB_OK,"Ejemplo Word Doc Open","Se abrió el documento exitosamente.")
	ElseIf @error = 1 Then
		MsgBox($MB_OK,"Ejemplo Word Doc Open","$oWord no es un objeto de tipo Word.")
	ElseIf @error = 2 Then
		MsgBox($MB_OK,"Ejemplo Word Doc Open","El documento especificado no existe.")
	EndIf
EndFunc

Si ejecutamos el script, nos abrirá el documento que queremos y además mostrará el mensaje “Se abrió el documento exitosamente.”.

Ahora modifiquemos el código y asignemos a la variable $oWord un valor numérico en vez de un objeto de Word.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

#include <Word.au3>
#include <MsgBoxConstants.au3>

AbrirDocumentoWord()

Func AbrirDocumentoWord()
	Local $oWord = 234
	_Word_DocOpen($oWord,@DesktopDir&"\Prueba UDF WordDocOpen.docx")
	If @error = 0 Then
		MsgBox($MB_OK,"Ejemplo Word Doc Open","Se abrió el documento exitosamente.")
	ElseIf @error = 1 Then
		MsgBox($MB_OK,"Ejemplo Word Doc Open","$oWord no es un objeto de tipo Word.")
	ElseIf @error = 2 Then
		MsgBox($MB_OK,"Ejemplo Word Doc Open","El documento especificado no existe.")
	EndIf
EndFunc

Al hacer esto, volvamos a ejecutar el script, observamos que no abre el documento y el mensaje que mostrará en pantalla será "$oWord no es un objeto de tipo Word.".

Por último, cambiemos el nombre del documento que queremos abrir por alguno que no exista en el escritorio, por ejemplo “Hola Mundo.docx”.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

#include <Word.au3>
#include <MsgBoxConstants.au3>

AbrirDocumentoWord()

Func AbrirDocumentoWord()
	Local $oWord = _Word_Create()
	_Word_DocOpen($oWord,@DesktopDir&"\Hola Mundo.docx")
	If @error = 0 Then
		MsgBox($MB_OK,"Ejemplo Word Doc Open","Se abrió el documento exitosamente.")
	ElseIf @error = 1 Then
		MsgBox($MB_OK,"Ejemplo Word Doc Open","$oWord no es un objeto de tipo Word.")
	ElseIf @error = 2 Then
		MsgBox($MB_OK,"Ejemplo Word Doc Open","El documento especificado no existe.")
	EndIf
EndFunc

Ejecutamos el script nuevamente y tampoco se abrirá el documento por obvias razones, pero el mensaje que se mostrará en pantalla será “El documento especificado no existe.”.

• _Word_DocSave: Guarda el documento de Word especificado. La sintaxis es la siguiente.

1	_Word_DocSave($oDoc)

• $oDoc, es un objeto de documento de Word.
• La función retorna 1 si el documento se guarda correctamente.
• La función retorna 0 en caso de no guardar el documento y establece la macro @error con un valor distinto de cero. Los posibles valores que puede tomar esta macro aparte del cero son: 1 -> Si $oDoc no es un objeto, 2 -> El documento especificado no se ha guardado antes, para evitar esto utilice _Word_DocSaveAs() antes, y 3 -> Si ocurre un error al guardar el documento.
• Si el documento no se ha guardado antes o se ha abierto en modo lectura, aparecerá el cuadro de diálogo Guardar como para que usted elija la ubicación y el nombre del archivo de Word.

Ejemplo: Utilizando las UDFs para Word vamos a abrir el documento Prueba UDF WordDocOpen que tenemos en nuestro escritorio, luego simularemos el ingreso de texto en el documento y por último guardaremos los cambios.

Para lograr esto, primero crearemos un script con nombre WordDocSave y segundo, coloquemos el siguiente código.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

#include <Word.au3>
#include <MsgBoxConstants.au3>

Local $oWord
Local $oDoc
Local $sString = "Esto es un ejemplo de la función _Word_DocSave()."

AbrirDocumento()
IngresarTexto()
GuardarDocumento()

Func AbrirDocumento()
	$oWord = _Word_Create()
	$oDoc = _Word_DocOpen($oWord,@DesktopDir&"\Prueba UDF WordDocOpen.docx")
EndFunc

Func IngresarTexto()
	;Activa (enfoca) una ventana especifica
	WinActivate("Prueba UDF WordDocOpen.docx - Word")
	;Envío una cadena de caracteres a la ventana
	ControlSend("Prueba UDF WordDocOpen.docx - Word","","[CLASSNN:_WwG1]",$sString)
EndFunc

Func GuardarDocumento()
	MsgBox($MB_OK,"Ejemplo DocSave",_Word_DocSave($oDoc))
EndFunc

Si corremos el script, se hará lo explicado anteriormente y para probar si en verdad guardó, hacemos que muestre un mensaje, este mensaje tendrá un valor de 1 si los cambios hechos fueron guardados y 0 en caso de no guardar nada.

• _Word_Quit: Cierra la aplicación de Word y elimina la referencia del objeto. La sintaxis es la siguiente.

1 2	_Word_Quit($oAppl[,$iSaveChanges=$WdDoNotSaveChanges [,$iOriginalFormat=$WdWordDocument[,$bForceClose=False]]])

• Los corchetes representan las partes de la sintaxis que son opcionales.
• $oAppl, es un objeto de Word retornado por un llamado anterior a la función _Word_Create().
• $iSaveChanges, especifica si el documento debe guardarse antes de cerrar la aplicación de Word. Puede ser una de las enumeraciones WdSaveOptions, por defecto viene con la constante $WdDoNotSaveChanges. Para utilizar estas constantes globales debe incluir el archivo WordConstants.au3 en su script.
• Ingresa al enlace UDF Word Quit para conocer más sobre los parámetros de esta UDF y otras observaciones a tener en cuenta.
• Si la función tiene éxito, es decir, cierra la aplicación de Word entonces retorna 1.
• Si la función fracasó, es decir no cerró la aplicación de Word, retorna 0 y la macro @error toma un valor distinto a cero. Los valores aparte de 0 que esta macro puede tener son los siguientes: 1 -> Si $oAppl no es un objeto y 2-> Error retornado por el método Application.Quit.

Ejemplo: Creamos un script con nombre WordQuit y en él coloquemos el siguiente código.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

#include <Word.au3>

;Decalaración de variables
Local $oWord
Local $sTexto = "El valor de _Word_Quit es: "
Local $sTexto2 = "El valor de @error es: "

;Se crea una instancia de Word
$oWord = _Word_Create()

;Añade un documento (hoja) al archivo de Word
_Word_DocAdd($oWord)

;Pausa la ejecución durante 2 segundos
Sleep(2000)

;Muestra el valor de la función y cierra la aplicación de Word
MsgBox(0,"Ejemplo WordQuit",$sTexto&_Word_Quit($oWord))

;Muestra el valor de @error
MsgBox(0,"Ejemplo WordQuit",$sTexto2&@error)

Después de escribir el código, lo ejecutamos y nos abrirá un nuevo documento en blanco de Word y después de 2 segundos se cerrará la aplicación. Luego, muestra un mensaje con el valor que retorna la función y como el cierre de la aplicación fue exitoso, entonces devuelve 1 y debido a esto, la macro @error queda con el valor de 0.

Ahora modifiquemos el código.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

#include <Word.au3>

Local $oWord
Local $sTexto = "El valor de @error es: "

;Se crea una instancia de Word
$oWord = 234

;Añade un documento (hoja) al archivo de Word
_Word_DocAdd($oWord)

;Pausa la ejecución durante 2 segundos
Sleep(2000)

;Cierra la aplicación de Word
_Word_Quit($oWord)

;Muestra el valor de @error
MsgBox(0,"Ejemplo WordQuit",$sTexto&@error)

Cuando corramos el script, veremos que no se abre la aplicación de Word y mucho menos se cierra, esto se debe a que la variable $oWord no recibe un objeto sino un entero y, por ende, el valor de la macro @error toma el valor de 1.

UDFs Microsoft Excel

A continuación, se verán algunas funciones que cuenta AutoIt para el manejo de archivos de Excel. Si desea encontrar la lista completa puede ingresar al siguiente enlace: Funciones Definidas Por El Usuario (UDFs).

Nota: Para utilizar las funciones de Excel, usted debe incluir el archivo “Excel.au3” en su script usando la línea #include <Excel.au3>.

• _Excel_Open: Se conecta a una instancia de Excel existente o crea una nueva. Su sintaxis se muestra a continuación.

1 2	_Excel_Open([$bVisible=True[,$bDislplayAlerts=False [,$bScreenUpdating=True[,$bInteractive=True[,$bForceNew=False]]]])

• Los corchetes representan las partes opcionales de la sintaxis.
• $bVisible, especifica si la aplicación estará visible. Por defecto el valor de este parámetro es True.
• $bDisplayAlerts, si este parámetro es False, suprime todas las indicaciones y mensajes de alerta al abrir un workbook de Excel. El valor por defecto es False.
• •$bScreenUpdating, si este parámetro es False, no muestra la actualización de la pantalla. El valor predeterminado es False.
• $bInteractive, si es False, se bloquean todas las entradas por teclado y mouse en Excel, a excepción de las entradas a cuadros de diálogos). El valore predeterminado es True.
• $bForceNew, si es True, obliga a crear una nueva instancia de Excel incluso si ya hay una en ejecución.
• • Si la función se conecta o crea una instancia de Excel, es decir, tiene éxito, cambia el macro @ extended por alguno de estos valores: 0 -> Si Excel ya se encontraba en ejecución y 1 -> Si Excel no estaba en ejecución o $bForceNew se estableció en True.
• Si la función falla, es decir, no se conecta o no crea una instancia de Excel devuelve 0 y el valor de la macro @error en 1.

Ejemplo: Creemos un script al cual le pondremos como nombre ExcelOpen y acto seguido colocamos el siguiente código.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

#include <Excel.au3>
#include <MsgBoxConstants.au3>

Local $sTexto1 = "Excel ya estaba en ejecución."
Local $sTexto2 = "Excel no se estaba ejecutando o $bForceNew es True."

_Excel_Open()

If @extended = 0 Then
	MsgBox($MB_OK,"Ejemplo ExcelOpen",$sTexto1)
ElseIf @extended = 1 Then
	MsgBox($MB_OK,"Ejemplo ExcelOpen",$sTexto2)
EndIf

Cuando ejecutemos el script, se nos abrirá la aplicación de Excel y como no había ninguna abierta, entonces la macro @extended tomará el valor de 1 y mostrará el siguiente mensaje.

Si abrimos un archivo de Excel y después ejecutamos el script, la UDF _Excel_Open se conectará a esta instancia haciendo que la macro @extended tome el valor de 0 y arroje el siguiente resultado.

• _Excel_BookNew: Crea un nuevo workbook. La sintaxis es la siguiente.

1	_Excel_BookNew($oExcel[,$iSheets=Default])

• Los corchetes representan la parte de la sintaxis que es opcional.
• $oExcel, es el objeto de la aplicación de Excel donde se va a crear el nuevo workbook.
• $iSheets, es el número de hojas que se van a crear en el workbook. El número máximo de hojas que se puede crear es 255.
• La función retorna en caso de éxito un nuevo objeto Workbook.
• La función en caso de fallar retorna 0 y puede establecer la macro @error en 4 valores aparte del cero. Esos valores van del 1 al 4, pero los más importantes son: 1 -> Si $oExcel no es un objeto y 4 -> Si el parámetro $iSheets tiene un valor menor que 1 o mayor que 255.

Ejemplo: Crearemos un script con nombre ExcelBookNew y en él escribimos el siguiente código.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

#include <Excel.au3>
#include <MsgBoxConstants.au3>

Local $oExcel
Local $sEjemplo = "Ejemplo ExcelBookNew"
Local $sTexto1 = "Se creó un nuevo libro de trabajo exitosamente."
Local $sTexto2 = "$oExcel no es un objeto de tipo Excel."
Local $sTexto3 = "El número de hojas no está dentro del rango permitido."

$oExcel = _Excel_Open()

_Excel_BookNew($oExcel)

If @error = 0 Then
	MsgBox($MB_OK,$sEjemplo,$sTexto1)
ElseIf @error = 1 Then
	MsgBox($MB_OK,$sEjemplo,$sTexto2)
ElseIf @error = 4 Then
	MsgBox($MB_OK,$sEjemplo,$sTexto3)
EndIf

Si ejecutamos este script, se nos abre un woorkbook y, por ende, la macro @error quedara con el valor 0 mostrando el mensaje “Se creó un nuevo libro de trabajo exitosamente.”.

Ahora en la variable $oExcel le asignaremos una cadena de caracteres en vez de un objeto de Excel y lo ejecutamos. Observaremos que la aplicación no se abre y la macro @error tendrá un valor de 1 mostrando el mensaje “$oExcel no es un objeto de tipo Excel.”.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

#include <Excel.au3>
#include <MsgBoxConstants.au3>

Local $oExcel
Local $sEjemplo = "Ejemplo ExcelBookNew"
Local $sTexto1 = "Se creó un nuevo libro de trabajo exitosamente."
Local $sTexto2 = "$oExcel no es un objeto de tipo Excel."
Local $sTexto3 = "El número de hojas no está dentro del rango permitido."

$oExcel = "Q-Vision Technologies"

_Excel_BookNew($oExcel)

If @error = 0 Then
	MsgBox($MB_OK,$sEjemplo,$sTexto1)
ElseIf @error = 1 Then
	MsgBox($MB_OK,$sEjemplo,$sTexto2)
ElseIf @error = 4 Then
	MsgBox($MB_OK,$sEjemplo,$sTexto3)
EndIf

Por último, en la UDF _Excel_BookNew(), le pondremos en el parámetro $iSheets 256 para que nos cree esa cantidad de hojas en el workbook. Este valor está por fuera del rango permitido ocasionando que falle la ejecución y haciendo que la macro @error tome el valor de 4.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

Local $oExcel
Local $sEjemplo = "Ejemplo ExcelBookNew"
Local $sTexto1 = "Se creó un nuevo libro de trabajo exitosamente."
Local $sTexto2 = "$oExcel no es un objeto de tipo Excel."
Local $sTexto3 = "El número de hojas no está dentro del rango permitido."

$oExcel = _Excel_Open()

_Excel_BookNew($oExcel,256)

If @error = 0 Then
	MsgBox($MB_OK,$sEjemplo,$sTexto1)
ElseIf @error = 1 Then
	MsgBox($MB_OK,$sEjemplo,$sTexto2)
ElseIf @error = 4 Then
	MsgBox($MB_OK,$sEjemplo,$sTexto3)
EndIf

• _Excel_Close: Cierra la aplicación de Excel. La sintaxis es la siguiente.

1	_Excel_Close($oExcel[,$bSaveChanges=True[,$bForceClose=False]])

• Los corchetes representan la parte de la sintaxis que es opcional.
• $oExcel, es un objeto de Word.
• $bSaveChanges, especifica si las hojas modificadas deberían ser guardadas antes de cerrar Excel. Por defecto, este parámetro es True.
• $bForceClose, Si el parámetro es True, la aplicación es cerrada incluso cuando no fue iniciada por la función _Excel_Open(). El parámetro por defecto es False.
• Si la función cierra el Excel entonces devuelve el valor de 1.
• Si la función falla, es decir, no cierra la aplicación de Excel, entonces retorna 0 y cambia la macro @error a un valor distinto a cero. Los valores que puede tomar aparte de cero son: 1-> $oExcel no es un objeto de tipo Excel, 2 -> Error devuelto por el método Application.Quit y 3 -> Error retornado por el método Application.Save.

Ejemplo: Creamos un script con nombre ExcelClose y en ella escribimos el siguiente código.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

#include <Excel.au3>

Local $oExcel
Local $oWorkBook
Local $sTexto1 = "La UDF _Word_Close retorna el valor de: "
Local $sTextoEjemplo = "Ejemplo ExcelClose"

AbrirExcel()
CerrarExcel()

Func AbrirExcel()
	$oExcel = _Excel_Open()
	$oWorkBook = _Excel_BookNew($oExcel,3)
EndFunc

Func CerrarExcel()
	Sleep(3000)
	MsgBox(0,$sTextoEjemplo,$sTexto1&_Excel_Close($oExcel))
EndFunc

Cuando ejecutemos el script, se abre la aplicación de Excel con tres hojas y luego de 3 segundos se cerrará el archivo. Como el cierre fue exitoso, entonces la función _Excel_Close devolverá el valor de 1.