Trabajando con Apache OpenOffice

From Apache OpenOffice Wiki
< ES‎ | Manuales‎ | GuiaAOO‎ | TemasAvanzados‎ | Macros‎ | Python
Revision as of 22:54, 26 April 2013 by Mauriciobaeza (Talk | contribs)

Jump to: navigation, search


Conceptos iniciales

Este es el tema más importante para crear macros, de forma sencilla, pero se ven las bases para trabajar con todo AOO, por eso es importante no avanzar en estas notas, sin antes haber comprendido a cabalidad los temas presentes.

UNO (Universal Network Objects), es la especificación que da acceso a todos los objetos de Apache OpenOffice.

El API (Application Programer Interface) de Apache OpenOffice proporciona el acceso a toda la funcionalidad de AOO, independientemente del lenguaje.

La comunicación entre objetos UNO se basa en interfaces de objeto. Las interfaces pueden ser vistos desde el exterior o el interior de un objeto y proporcionan formas de ver o manipular el objeto.

Los servicios son agrupaciones lógicas de interfaces, son la forma en que un mismo objeto pueda ofrecer la funcionalidad de varias interfaces.

Los servicios se pueden implementar en librerías compartidas llamadas componentes UNO, con Python podemos crear componentes nuevos y generalmente el usuario final las recibe como una extensión OXT.

Los modulos pueden agrupar submodulos, servicios, excepciones, constantes, enumeraciones, etc, se utilizan para especificar bloques coherentes en la API, esto permite tener un APi bien estructurada.


Creando servicios

Para crear un servicio, usamos la fabrica de servicios (com.sun.star.lang.XMultiComponentFactory), una interfaz especial para crear nuevos servicios, pero para llegar a ella, tenemos que hacerlo a traves de la interfaz ComponentContext (com.sun.star.uno.XComponentContext), como puedes verlo en la siguiente imagen.

ComponentContext y ServiceManager


En pyUNO tenemos dos formas de acceder a esta interfaz, las dos son equivalentes por lo que puedes usar la que prefieras. En la introducción a Python se mencionó que la mayoría de sus herramientas están disponibles en librerias, estás librerias tienen que importarse antes de poder usarse, en nuestro caso importaremos la librería uno que nos da acceso (entre otras cosas) al contexto de ejecución de AOO.

import uno
 
def pruebas():
    ctx1 = XSCRIPTCONTEXT.getComponentContext()
    ctx2 = uno.getComponentContext()
    return

Template:Documentation/Note


Ahora si, podemos acceder a la fábrica de servicios con el método getServiceManager().

import uno
 
def pruebas():
    ctx = uno.getComponentContext()
    sm = ctx.getServiceManager()
    return


Pero... ¿como sabemos que este objeto (ComponentContext) tiene este método getServiceManager()? porque lo estamos demostrando, si, también por eso, pero también porque puedes ver su documentación (com.sun.star.uno.XComponentContext) en el API de AOO, pero más importante aún, porque podemos hacer que el mismo objeto te diga todo lo que sabe hacer. Para ello haremos uso de una magnifica extensión que te tiene que acompañar el resto de tus días como programador de macros Python, nos referimos a MRI. Instala (tal vez tengas que reiniciar AOO para poder usarla) y la probamos de la siguiente manera.

import uno
 
def pruebas():
    ctx = uno.getComponentContext()
    # llamamos a la extensión MRI y le pasamos el objeto a inspeccionar
    mri(ctx)
    sm = ctx.getServiceManager()
    return 
 
def mri(target):
    ctx = uno.getComponentContext()
    sm = ctx.getServiceManager()    
    mri = sm.createInstanceWithContext('mytools.Mri', ctx)
    mri.inspect(target)
    return


Observa en la imágen siguiente, como hemos seleccionado los métodos del objeto y nos lista todos los que tenga, hemos remarcado el que por ahora nos interesa getServiceManager(), observa al final de la línea que efectivamente este método nos devuelve una instancia de la interfaz com.sun.star.lang.XMultiComponentFactory.

Usando la extensión MRI


La gran ventaja de usar esta extensión (que por cierto esta hecha en Python), es que siempre te devolverá la información directamente del objeto, a esto se le llama instrospección. Acostumbrate a usarla.

Ahora si, ya podemos crear una instancia de cualquier servicio o interfaz disponible en AOO, por ejemplo, el servicio com.sun.star.frame.Desktop.

import uno
 
def pruebas():
    ctx = uno.getComponentContext()
    sm = ctx.getServiceManager()
    desktop = sm.createInstanceWithContext('com.sun.star.frame.Desktop', ctx)
    return


Existe una forma alternativa de crear este servicio, usando XSCRIPTCONTEXT de la siguiente manera.

    XSCRIPTCONTEXT.getDesktop()

Template:Documentation/Note


¿Y para que sirve este servicio? Entre otras cosas para crear nuevos documentos.

nuevo = desktop.loadComponentFromURL('private:factory/scalc', '_default', 0, ())

Más adelante veremos a detalle este método y otros relacionados con los documentos de AOO.


El servicio com.sun.star.frame.Desktop es la instancia de la administración central para todas las aplicaciones AOO. Todas las ventanas de la aplicación AOO se organizan en una jerarquía de marcos que contienen componentes visibles.

Desktop administra los componentes y marcos.

Para los fines de crear macros es suficiente que recuerdes que, Desktop es el marco raíz de toda la jerarquía de documentos.


Para crear la instancia del servicio com.sun.star.frame.Desktop usamos un contexto y usamos el método createInstanceWithContext. Otros servicios no requieren de contexto para ser instanciados y usados, por ejemplo, el servicio com.sun.star.util.PathSettings que nos sirve para obtener las rutas de trabajo actuales en AOO, para estos casos usamos el método createInstance.

    rutas = sm.createInstance('com.sun.star.util.PathSettings')
    # mostramos la ruta de trabajo del usuario
    print (rutas.Work)


Ahora que ya sabemos instanciar servicios, veamos de nuevo nuestra macro para mostrar un mensaje en pantalla y analicemosla línea a línea para que veas que sencillo es, además, nos servirá para ver otros detalles al programar con Python en AOO. La macro tiene ahora unos ligeros cambios para que trabaje mejor y para explicar algunas cosas, veamos cuales.

def msgbox(message):
    from com.sun.star.awt import Rectangle
    from com.sun.star.awt.MessageBoxButtons import BUTTONS_OK
 
    if not isinstance(message, (unicode, str)):
        message = str(message)
    ctx = uno.getComponentContext()
    sm = ctx.getServiceManager()
    toolkit = sm.createInstanceWithContext('com.sun.star.awt.Toolkit', ctx)
    MsgBox = toolkit.createMessageBox(
                                    toolkit.getDesktopWindow(),
                                    Rectangle(),
                                    'infobox',
                                    BUTTONS_OK,
                                    'pyUNO',
                                    message)
    return MsgBox.execute()


En la primer línea declaramos nuestra macro, su nombre y los argumentos que necesita, en este caso solo uno message que será el mensaje a mostrar.

def msgbox(message):


En la segunda línea, estamos importando (import) la estructura Rectangle desde (from) el modulo com.sun.star.awt.module-ix.

    from com.sun.star.awt import Rectangle

Las estructuras son un conjunto de valores relacionados, valores que pueden ser de tipos diferentes, pero que son mostrados como una unidad lógica, por ejemplo, la estructura com.sun.star.awt.Rectangle hace referencia a un área rectangular estableciendo su posición y tamaño, en este caso, solo sirve para cumplir los argumentos del método para mostrar nuestro mensaje.


En la tercer línea, hacemos otra importación, pero esta vez la hacemos de una constante, específicamente la constante para mostrar el botón Aceptar (OK), estas constantes las puedes ver aquí: com.sun.star.awt.MessageBoxButtons

    from com.sun.star.awt.MessageBoxButtons import BUTTONS_OK


La cuarta línea esta vacía solo para separar la parte de importacion con el resto del código. En la siguiente línea hacemos una validación del argumento pasado a nuestra macro, si el argumento no es una instancia de la clase unicode o de la clase str, entonces la convertimos a str, esto nos permite pasar a nuestra macro, listas, tuplas, diccionarios y practicamente cualquier objeto, del cual, podremos ver su representación en texto, muchas veces, con información bastante útil.

    if not isinstance(message, (unicode, str)):
        message = str(message)


La siguiente línea ya la hemos estudiado, creamos una instancia del contexto donde se ejecuta AOO.

    ctx = uno.getComponentContext()


La siguiente línea también ya la hemos estudiado, creamos una instancia de la fabrica de servicios, una de las instancias más importantes y que usaras constantemente.

    sm = ctx.getServiceManager()


En la siguiente línea creamos una instancia con contexto de un nuevo servicio com.sun.star.awt.Toolkit, este servicio sirve, entre otras muchas cosas para crear ventanas y mensaje de texto, como el de nuestra macro.

    toolkit = sm.createInstanceWithContext('com.sun.star.awt.Toolkit', ctx)


En la penultima línea, usamos el método createMessageBox del servicio com.sun.star.awt.Toolkit para crear nuestro cuadro de mensaje, todos los argumentos de este método puedes verlo aquí: com.sun.star.awt.XMessageBoxFactory, pero aquí los explicamos uno a uno.

    MsgBox = toolkit.createMessageBox(
                                    toolkit.getDesktopWindow(),
                                    Rectangle(),
                                    'infobox',
                                    BUTTONS_OK,
                                    'pyUNO',
                                    message)

Aunque veas muchas líneas, el interpete la considera una sola, esto se logra al estar todos los argumentos entre paréntesis.

  • El primer argumento es la ventana padre (parent) donde será mostrado el cuadro de mensaje, observa como usamos de nuevo el servicio toolkit para recuperar (getDesktopWindow) la ventana padre de AOO.
  • El segundo argumento es el área rectangular del cuadro de mensaje, observa los dos paréntesis al final del nombre de la estructura, son necesarios para inicializarla.
  • El tercer argumento es el tipo de mensaje, dependiendo de este argumento se muestra el icono correspondiente, los valores permitidos son: infobox, warningbox, errorbox, querybox y messbox, si usas infobox, el siguiente argumento es ignorado.
  • El cuarto argumento sirve para mostrar botones de comando diferentes, como: Si, No, Cancelar, etc, que están establecidos en las constantes vistas más arriba.
  • El quinto argumento es el título del cuadro de mensaje.
  • Y por ultimo, el mensaje a mostrar, el cual ya validamos.


En la ultima línea al mismo tiempo que mostramos (ejecute) estamos retornando el cuadro de mensaje, esto nos da la posibilidad de capturar el botón al que le haya dado click el usuario, lo cual, veremos más adelante. Todas las macros retornan un valor, aun y cuando este sea un valor vacío (None).

    return MsgBox.execute()


Resumiendo, los servicio los instanciamos y las estructuras y constantes las importamos, y el punto más importante; acostúmbrate a usar, manejar y dominar, la extensión MRI, ella te dice todo lo necesario para trabajar con los objetos UNO de AOO, los demás, es sencillo.


El documento activo

Tenemos dos formas de acceder al documento activo.

    doc1 = XSCRIPTCONTEXT.getDocument()
    doc2 = desktop.getCurrentComponent()
    print (doc1.getIdentifier())
    print (doc2.getIdentifier())

Template:Documentation/Note


Si seguiste nuestra recomendación de asignar la macro de pruebas a una combinación de teclas disponible en todo AOO, prueba a abrir cada uno de los tipos de documentos que puedes ver en el menú Archivo->Nuevo->.

Tipos de documentos en AOO


Y a ejecutar la siguiente macro, teniendo como documento activo cada uno de ellos, es decir, activas uno y ejecutas la macro, activas otro y vuelves a llamar a la macro y así sucesivamente con todos.

def pruebas():
    ctx = uno.getComponentContext()
    sm = ctx.getServiceManager()
    desktop = sm.createInstanceWithContext('com.sun.star.frame.Desktop', ctx)
    doc = desktop.getCurrentComponent()
    print (doc.getIdentifier())
    return


Los mensajes devueltos en cada documento, son bastante ilustrativos de que tipo de documento se trata. Pero si probaste con todos, habrás notado que con la base de datos nos devuelve un error, si no lo has probado hazlo ahora. Para resolver este caso tenemos varias posibilidades, la primera es controlar la excepción como ya aprendimos en la introducción a Python.

    doc = desktop.getCurrentComponent()
    try:
        print (doc.getIdentifier())
    except:
        print ('Error al obtener el tipo de documento')


Pero... ¿estamos realmente seguros que ese es el error?, es mejor especificarlo y asegurarnos de que este es el error.

    doc = desktop.getCurrentComponent()
    try:
        print (doc.getIdentifier())
    except AttributeError:
        print ('Error al obtener el tipo de documento')


Tenemos otra alternativa donde no usamos controlador de excepciónes, si no una función que nos dice si un cierto atributo lo posee o no un objeto.

    doc = desktop.getCurrentComponent()
    if hasattr(doc, 'getIdentifier'):
        print (doc.getIdentifier())
    else:
        print ('Sin atributo getIdentifier')


Es mucho mejor esta segunda opción. Aun así, no podemos estar 100% seguros de que cuando no la tenga, el documento sea una base de datos, simplemente estamos excluyendo la posibilidad pero no lo estamos asegurando, probemos con otra propiedad.

    doc = desktop.getCurrentComponent()
    print (doc.getImplementationName())


Mucho mejor, ahora ya no tenemos errores, pero si probaste de nuevo con todos los tipos de documentos, habrás notado que con Impres y con Draw obtenemos el mismo resultado, por lo que no tenemos la certeza de que tipo de documento es, por lo que descartamos esta propiedad para nuestra finalidad que es identificar fehacientemente cada tipo de documento.

Ya vimos que cada objeto UNO soporta diferentes servicios e interfaces, asì que cada documento de AOO (que son objetos) soportan diferentes servicios, algunos son iguales, es decir, comúnes a todos, pero algunos pueden ser únicos para cada documento. Ya vimos como saber si un documento soporta una propiedad, pero para saber si soporta un servicio completo, cambiamos de método, ahora usamos supportsService que nos devuelve falso o verdadero según soporte o no el nombre del servicio pasado como argumento.

    res = doc.supportsService('com.sun.star.sheet.SpreadsheetDocument')
    mensaje = u'No soy una hoja de cálculo'
    if res:
        mensaje = u'Soy una hoja de cálculo'
    print(mensaje)


Y mejor aun, podemos saber todos los servicios que soporta un objeto con el método getSupportedServiceNames que nos devuelve una tupla con todos sus nombres.

    doc = desktop.getCurrentComponent()
    servicios = doc.getSupportedServiceNames()
 
    print(servicios)


Te queda de tarea probar esta macro en cada uno de los documentos abiertos, incluso puedes probar también el IDE para AOOBasic que incorpora AOO y determinar que servicio usar para diferenciar sin duda cada tipo de documento.

Los documentos abiertos

Para acceder a todos los documentos abiertos en la sesión de AOO, usamos el método getComponents del objeto Desktop, si usas MRI, notarás que este método nos devuelve una instancia de la interfaz com.sun.star.container.XEnumerationAccess

    desktop = sm.createInstanceWithContext('com.sun.star.frame.Desktop', ctx)
    documentos = desktop.getComponents()


Esta interfaz (com.sun.star.container.XEnumerationAccess) tiene un solo método llamado createEnumeration que nos duelve una instancia de la interfaz com.sun.star.container.XEnumeration la cual a su vez tiene solo dos métodos, el primero para saber si tenemos más elementos en la enumeración: hasMoreElements y el segundo para acceder al siguiente elemento nextElement, veamoslo con un ejemplo.

def pruebas():
    ctx = uno.getComponentContext()
    sm = ctx.getServiceManager()
 
    desktop = sm.createInstanceWithContext('com.sun.star.frame.Desktop', ctx)
    documentos = desktop.getComponents()
    enum = documentos.createEnumeration()
    # mientras tengamos elementos
    while enum.hasMoreElements():
        # obtenemos el siguiente elemento
        doc = enum.nextElement()
        # mostrámos el tipo de documento
        mensaje = obtener_tipo(doc)
        print(mensaje)
    return 
 
def obtener_tipo(doc):
    tipo = {'com.sun.star.sheet.SpreadsheetDocument': 'Calc',
            'com.sun.star.text.TextDocument': 'Writer',
            'com.sun.star.presentation.PresentationDocument': 'Impress',
            'com.sun.star.drawing.DrawingDocument': 'Draw',
            'com.sun.star.sdb.OfficeDatabaseDocument': 'Base',
            'com.sun.star.formula.FormulaProperties': 'Math',
            'com.sun.star.script.BasicIDE': 'Basic'}
    # iteramos entre los tipos de documentos
    for t in tipo:
        # validamos si soporta el servicio
        if doc.supportsService(t):
            # devolvemos el tipo de documento
            return 'Soy %s' % tipo[t]
    # si termina sin encontrar un tipo
    return 'No se que tipo soy'


Observa como usamos una macro de apoyo para saber que tipo de documento es. Una enumeración no es más que una lista de objetos y es una forma muy común y a veces la única de acceder a ciertos objetos en AOO, es importante que la recuerdes.

Rutas de archivos y directorios

Apache OpenOffice, al ser multiplataforma, hace uso de las rutas de archivos y directorios, en el formato URL, por ejemplo.

file:///home/usuario/datos/miarchivo.ods

file:///d:/datos/miarchivo.ods


Toma en cuenta que este formato hace uso de los caracteres 0-9, a-z y A-Z, y cualquier otro carácter será convertido y mostrado con su respectivo código, por ejemplo, los espacios los reemplazara con %20. Siempre que le pases una ruta de archivo a cualquier servicio de AOO, hazlo, casi como una regla, pasarle la ruta en formato Url, para ello, la libreria uno cuenta con dos funciones muy útiles que hacen el trabajo systemPathToFileUrl y fileUrlToSystemPath, veamos como se usan.

import uno
 
def rutas():
 
    ruta = "/home/mau/Mi archivo de Calc.ods"
    print (ruta)
 
    # La convertimos al formato URL
    ruta = uno.systemPathToFileUrl(ruta)
    print (ruta)
 
    # Regresamos al formato local
    ruta = uno.fileUrlToSystemPath(ruta)
    print (ruta)
 
    return


Abre varios documentos existentes y ejecuta la siguiente macro desde cada uno:

import uno
import os
 
def info_ruta():
    ctx = uno.getComponentContext()
    sm = ctx.getServiceManager()
    desktop = sm.createInstanceWithContext('com.sun.star.frame.Desktop', ctx)    
 
    doc = desktop.getCurrentComponent()
    # obtenemos la ruta en disco
    ruta =  doc.getURL()
    # obtenemos las diferentes partes de la ruta
    ruta, archivo = os.path.split(ruta)
    nombre, extension = os.path.splitext(archivo)
 
    print (ruta)
    print (uno.fileUrlToSystemPath(ruta))
    print (archivo)
    print (nombre)
    print (extension)
 
    return


Hemos importado una nueva librería de Python, os que entre otras muchas cosas, nos permite obtener información de las rutas de archivos como en la macro anterior.

En nuestros siguientes temas, veremos la importancia de usar las rutas de archivos y directorios en formato Url y recuerda que en S.O. Linux, se tiene en cuenta la diferencia entre mayúsculas y minúsculas.

Creando nuevos documentos

Abriendo, guardando y cerrando documentos

Algunas tareas comunes en documentos

Personal tools