Criando macros Java para o BrOffice.org

Criando macros Java para o BrOffice.org
1. Requisitos
–
BrOffice.org
–
JDK 5
2. Configurando o ambiente
–
Inclua o diretório dos binários do JDK na variável de ambiente PATH;
–
Acrescente os arquivos sandbox.jar, jurt.jar, ridl.jar, unoil.jar localizados em
<BrOo_Install>/program/classes na variável de ambiente CLASSPATH.
3. Criando a macro
–
Edite a macro no seu editor favorito
// exemplo de macro Java para o BrOffice.org Calc
// classes Java
// tipos UNO usados na macro
import com.sun.star.script.provider.XScriptContext;
import com.sun.star.uno.UnoRuntime;
import com.sun.star.uno.AnyConverter;
import com.sun.star.uno.Type;
import com.sun.star.frame.XComponentLoader;
import com.sun.star.lang.XComponent;
import com.sun.star.beans.PropertyValue;
import com.sun.star.container.XIndexAccess;
import com.sun.star.sheet.XSpreadsheetDocument;
import com.sun.star.sheet.XSpreadsheet;
// podemos incluir todos os tipos de um módulo
// import com.sun.star.sheet.*;
// classe JavaCalc
public class JavaCalc {
// toda macro Java recebe a interface
// XScriptContext como 1o. parâmetro
public static void exCalc (XScriptContext xSc)
throws Exception
{
// cria novo documento do Calc
XSpreadsheetDocument xDoc = criaDocCalc(xSc);
// obtem a 1a. planilha no documento
XIndexAccess xIA = (XIndexAccess)
UnoRuntime.queryInterface(XIndexAccess.class, xDoc.getSheets());
XSpreadsheet xSheet = (XSpreadsheet) AnyConverter.toObject(
new Type(com.sun.star.sheet.XSpreadsheet.class), xIA.getByIndex(0));
// preenche células
preencheCelulas (xSheet);
} // exCalc
// cria um novo documento do Calc
private static XSpreadsheetDocument criaDocCalc(XScriptContext xSc)
throws Exception
{
XComponentLoader loader = (XComponentLoader)
UnoRuntime.queryInterface(XComponentLoader.class, xSc.getDesktop());
XComponent comp = loader.loadComponentFromURL(
"private:factory/scalc", "_blank", 4, new PropertyValue[0]);
XSpreadsheetDocument doc = (XSpreadsheetDocument)
UnoRuntime.queryInterface(XSpreadsheetDocument.class, comp);
return doc;
} // criaDocCalc
// preenche as células
private static void preencheCelulas (XSpreadsheet xSheet)
throws Exception
{
// obter célula A1
xSheet.getCellByPosition(0, 0).setFormula("Uma cadeia");
// obter célula B1
xSheet.getCellByPosition(1, 0).setValue(1234.56);
} // preencheCelulas
} // JavaCalc
–
Compile o código fonte
> javac
–
JavaCalc.java
Após a compilação, junte os arquivos *.class num pacote jar
> jar
-cvf
JavaCalc.jar
JavaCalc.class
4. Criando o arquivo parcel-descriptor.xml
<?xml version="1.0" encoding="UTF-8"?>
<parcel language="Java" xmlns:parcel="scripting.dtd">
<script language="Java">
<locale lang="pt-BR">
<displayname value="JavaCalc.Java"/>
<description>
Exemplo de Macro para o Calc
</description>
</locale>
<functionname value="JavaCalc.exCalc"/>
<logicalname value="JavaCalc.exCalc"/>
<languagedepprops>
<prop name="classpath" value="JavaCalc.jar"/>
</languagedepprops>
</script>
</parcel>
O arquivo parcel-descriptor.xml contém informações relevantes sobre a macro. Vejamos algumas:
script: define as características de uma macro. Para cada macro no jar, crie uma marca < script >;
locale: define as características da língua, uma mesma macro pode ter várias marcas < locale >;
displayname: recebe o nome a ser exibido na interface gráfica;
description: contém uma breve descrição da macro;
functionname: contém o nome do método que dispara a macro, precedido pelo nome da classe;
languagedepprops: relaciona as dependências da macro.
Use este exemplo como modelo, alterando apenas os atributos dos marcadores XML.
5. Instalando a macro
As macros Java devem residir em suas próprias pastas, sob o diretório Scripts/java. Para um usuário
em particular, a pasta Scripts/java deve ser criada.
–
Para um usuário
Copie os arquivos jar e parcel para o diretório <BrOo_User_install>/user/Scripts/java/JavaCalc
–
Para todos os usuários (necessário direitos de escrita)
Copie os arquivos jar e parcel para o diretório <BrOo_install>/share/Scripts/java/JavaCalc
–
Num documento (documentos ODF são arquivados no formato zip)
. expanda o documento na pasta nome_documento
. crie uma pasta Scripts/java sob nome_documento
. copie os arquivos jar e parcel para Scripts/java/JavaCalc
. comprima a pasta nome_documento
6. Executando a macro
–
O JRE deve estar ativo no BrOffice.org, verifique em:
Ferramentas >> Opções >> Broffice.org >> Java
–
Para selecionar e executar a macro: Ferramentas >> Macros >> Executar macro
7. Detalhes da programação UNO / Java
A programação UNO / Java é apresentada na documentação e nos diversos exemplos do SDK do
OpenOffice.org. Ela é explicada detalhadamente no The Developer's Guide (parte do SDK).
Objeto XScriptContext
As macros Java recebem, como 1º argumento, a interface XScriptContext, que possui três
métodos de acesso aos objetos de entrada da API. São eles:
com.sun.star.frame.XModel getDocument ( )
Retorna o modelo do documento para o qual a macro foi chamada
com.sun.star.frame.XDesktop getDesktop ( )
Retorna a interface XDesktop, responsável pelo acesso e carga de documentos
com.sun.star.uno.XComponentContext getComponentContext ( )
Retorna a interface XComponentContext, usada para criar instâncias de outros objetos
Passagem de parâmetros
Os argumentos são passados num vetor do tipo Object (2º parâmetro):
public void minhaMacro (XScriptContext xSC,
Object [ ] args)
Cada elemento do vetor é do tipo UNO Any e deve ser convertido adequadamente (veja
abaixo).
Fontes de erro
As fontes de erros mais comuns são:
–
não inclusão ( import ) dos tipos UNO usados na macro, por exemplo:
import com.sun.star.script.provider.XScriptContext;
–
não consulta das interfaces implementadas por um dado tipo, antes de utilizar um método:
XIndexAccess xIA = (XIndexAccess)
UnoRuntime.queryInterface(XIndexAccess.class, xDoc.getSheets());
–
não conversão dos tipos UNO any antes da sua utilização:
XSpreadsheet xSheet = (XSpreadsheet) AnyConverter.toObject(
new Type(com.sun.star.sheet.XSpreadsheet.class), xIA.getByIndex(0));
aqui, o método getByIndex() retorna um objeto UNO do tipo any.
–
não observação do mapeamento de tipos UNO <==> Java.
8. Mais informações
–
Exemplos do BrOffice.org em: <BrOo_install>/share/Scripts/java
–
Recursos para desenvolvimento no OpenOffice.org
http://development.openoffice.org
–
API do OpenOffice.org
http://api.openoffice.org
–
Projeto Programação do BrOffice.org
http://broffice.org/progr/prj_macros.html
9. Sobre este documento
Licença: Este documento está licenciado sob uma Licença Creative Commons Atribuição –
UsoNãoComercial – Compartilhamento pela mesma licença. Para ver uma cópia desta licença,
visite http://creativecommons.org/licenses/by-nc-sa/2.0/br/ ou envie uma carta para Creative
Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
Todas as marcas registradas citadas no documento pertencem aos seus legítimos proprietários.
Autor: Noelson Alves Duarte, em 14 de novembro de 2006.