Serviço ScriptForge.Basic

O serviço ScriptForge.Basic propõe uma coleção de métodos LibreOffice Basic a serem executados em um contexto Python. Os métodos de serviço Basic reproduzem a sintaxe e o comportamento exatos das funções integradas do Basic.

note

Este serviço está disponível a partir do LibreOffice 7.2 em diante.


Exemplo típico:


   svc.MsgBox('Isto tem que ser mostrado em uma caixa de diálogo')
  
warning

O serviço ScriptForge.Basic é limitado aos scripts em Python.


Invocando o Serviço

Antes de usar o serviço Basic, é necessário importar o método CreateScriptService() do módulo scriptforge:


    from scriptforge import CreateScriptService
    svc = CreateScriptService("Basic")
  

Propriedades

Nome

Somente leitura

Tipo

Descrição

MB_OK, MB_OKCANCEL, MB_RETRYCANCEL, MB_YESNO, MB_YESNOCANCEL

Sim

inteiro

Valores: 0, 1, 5, 4, 3

MB_ICONEXCLAMATION, MB_ICONINFORMATION, MB_ICONQUESTION, MB_ICONSTOP

Sim

inteiro

Valores: 48, 64, 32, 16

MB_ABORTRETRYIGNORE, MB_DEFBUTTON1, MB_DEFBUTTON2, MB_DEFBUTTON3

Sim

inteiro

Valores: 2, 128, 256, 512

IDABORT, IDCANCEL, IDIGNORE, IDNO, IDOK, IDRETRY, IDYES

Sim

inteiro

Valores: 3, 2, 5, 7, 1, 4, 6
Constantes que indicam o botão selecionado em MsgBox.

StarDesktop

Sim

Objeto
UNO

O objeto StarDesktop representa o Centro de Partica do LibreOffice.


Lista de Métodos no Serviço Basic

CDate
CDateFromUnoDateTime
CDateToUnoDateTime
ConvertFromUrl
ConvertToUrl
CreateUnoService
DateAdd
DateDiff
DatePart

DateValue
Format
GetDefaultContext
GetGuiType
GetPathSeparator
GetSystemTicks
GlobalScope.BasicLibraries
GlobalScope.DialogLibraries
InputBox

MsgBox
Now
RGB
ThisComponent
ThisDatabaseDocument
Xray




CDate

Converte uma expressão numérica ou uma string para um objeto nativo Python do tipo datetime.datetime.

note

Este método expõe a função interna do Basic CDate para scripts em Python.


Sintaxe:

svc.CDate(expression: any): obj

Parâmetros:

expression: uma expressão numérica ou uma string representando uma data.

Quando converter uma expressão de texto, a data e a hora devem ser inseridas em um dos padrões de aceitação da data definidos para sua configuração de localidade (veja - Configurações de idioma - Idiomas) ou no formato de data ISO (momentaneamente, apenas o formato ISO com hifens, por exemplo, "2012-12-31" é aceito). Em expressões numéricas, os valores à esquerda do decimal representam a data, a partir de 31 de dezembro de 1899. Os valores à direita do decimal representam as horas.

Exemplo:


    d = svc.CDate(1000.25)
    svc.MsgBox(str(d)) # 1902-09-26 06:00:00
    svc.MsgBox(d.year) # 1902
  

CDateFromUnoDateTime

Converte uma representação de data/tempo em UNO para um objeto nativo Python do tipo datetime.datetime.

Sintaxe:

svc.CDateFromUnoDateTime(unodate: uno): obj

Parâmetros:

unodate: Um objeto UNO que armazena data/tempo de um dos seguintes tipos: com.sun.star.util.DateTime, com.sun.star.util.Date ou com.sun.star.util.Time

Exemplo:

O exemplo a seguir cria um objeto com.sun.star.util.DateTime e converte-o para um objeto Python do tipo datetime.datetime.


    import uno
    uno_date = uno.createUnoStruct('com.sun.star.util.DateTime')
    uno_date.Year = 1983
    uno_date.Month = 2
    uno_date.Day = 23
    new_date = svc.CDateFromUnoDateTime(uno_date)
    svc.MsgBox(str(new_date)) # 1983-02-23 00:00:00
  

CDateToUnoDateTime

Converte uma representação de data em um objeto com.sun.star.util.DateTime.

Sintaxe:

svc.CDateToUnoDateTime(date: obj): uno

Parâmetros:

date: Um objeto Python que armazena data/tempo de um dos seguintes tipos: datetime.datetime, datetime.date, datetime.time, float (time.time) ou time.struct_time.

Exemplo:


    from datetime import datetime
    current_datetime = datetime.now()
    uno_date = svc.CDateToUnoDateTime(current_datetime)
    svc.MsgBox(str(uno_date.Year) + "-" + str(uno_date.Month) + "-" + str(uno_date.Day))
  

ConvertFromUrl

Retorna um caminho usando a notação do sistema para uma URL especificada em file:.

Sintaxe:

svc.ConvertFromUrl(url: str): str

Parâmetros:

url: Uma URL do tipo file:.

Valor de retorno:

Um caminho de arquivo no formato do sistema.

Exemplo:


    filename = svc.ConvertFromUrl( "file:///C:/Program%20Files%20(x86)/LibreOffice/News.txt")
    svc.MsgBox(filename)
  

ConvertToUrl

Retorna uma URL do tipo file: para um caminho especificado no formato do sistema.

Sintaxe:

svc.ConvertToUrl(systempath: str): str

Parâmetros:

systempath: Um caminho para nome de arquivo no formato do sistema, como uma string.

Valor de retorno:

Uma string no formato URL file:.

Exemplo:


    url = svc.ConvertToUrl( 'C:\Program Files(x86)\LibreOffice\News.txt')
    svc.MsgBox(url)
  

CreateUnoService

Cria uma instância de um serviço UNO com o ProcessServiceManager.

Sintaxe:

svc.CreateUnoService(servicename: str): uno

Parâmetros:

servicename: Um nome completo para um serviço, como por exemplo "com.sun.star.ui.dialogs.FilePicker" ou "com.sun.star.sheet.FunctionAccess".

Exemplo:


    dsk = svc.CreateUnoService('com.sun.star.frame.Desktop')
  

DateAdd

Adiciona um intervalo de datas ou tempo a uma data/tempo específica várias vezes e retorna a data/tempo resultante.

Sintaxe:

svc.DateAdd(interval: str, number: num, date: datetime): datetime

Parâmetros:

interval: Uma expressão do tipo string da tabela a seguir, a qual especifica o intervalo de data ou tempo:

intervalo (valor da string)

Explicação

aaaa

Ano

q

Trimestre

m

Mês

y

Dia do ano

w

Dia da semana

ww

Semana do ano

d

Dia

h

Hora

n

Minuto

s

Segundos


number: Uma expressão numérica especificando quantas vezes o valor interval será adicionado (quando positivo) ou subtraído (quando negativo).

date: Uma data especificada do tipo datetime.datetime; o valor interval será adicionado a este valor de data/tempo.

Valor de retorno:

Um valor do tipo datetime.datetime.

Exemplo:


    dt = datetime.datetime(2004, 1, 31)
    dt = svc.DateAdd("m", 1, dt)
    print(dt)
  

DateDiff

Retorna o número de intervalos de data ou tempo entre dois valores de data/tempo específicos.

Sintaxe:

svc.DateDiff(interval: str, date1: datetime, date2: datetime, firstdayofweek = 1, firstweekofyear = 1): int

Parâmetros:

interval: Uma string com uma expressão definindo o intervalo de data, conforme detalhado anteriormente no método DateAdd.

date1, date2: Dois valores datetime.datetime a serem comparados.

firstdayofweek - Um parâmetro opcional que especifica o primeiro dia da semana.

Valor firstdayofweek

Explicação

0

Use o valor padrão do sistema

1

Domingo (padrão)

2

Segunda-feira

3

Terça-feira

4

Quarta-feira

5

Quinta-feira

6

Sexta-feira

7

Sábado


firstweekofyear - Um parâmetro opcional que especifica a primeira semana de um ano.

Valor firstweekofyear

Explicação

0

Use o valor padrão do sistema

1

A semana 1 é a semana com 1ro de janeiro (padrão)

2

A semana 1 é a primeira semana que contém quatro ou mais dias desse ano

3

A semana 1 é a primeira semana que contém somente dias do ano novo


Valor de retorno:

Um número.

Exemplo:


    date1 = datetime.datetime(2005,1, 1)
    date2 = datetime.datetime(2005,12,31)
    diffDays = svc.DateDiff('d', date1, date2)
    print(diffDays)
  

DatePart

A função DatePart retorna uma parte específica de uma data.

Sintaxe:

svc.DatePart(interval: str, date: datetime, firstdayofweek = 1, firstweekofyear = 1): int

Parâmetros:

interval: Uma string com uma expressão definindo um intervalo de data, conforme definido anteriormente no método DateAdd.

date: Objeto de data/tempo a partir da qual o resultado é calculado.

firstdayofweek, firstweekofyear: parâmetros opcionais que especificam, respectivamente, o primeiro dia da semana e a primeira semana do ano, conforme detalhado no método DateDiff.

Valor de retorno:

A parte extraída de um valor de data/tempo.

Exemplo:


    print(svc.DatePart("ww", datetime.datetime(2005,12,31)
    print(svc.DatePart('q', datetime.datetime(1999,12,30)
  

DateValue

Computa um valor de data a partir de uma string representando uma data.

Sintaxe:

svc.DateValue(date: str): datetime

Parâmetros:

Date:Expressão de texto que contém a data a calcular. Em contraste com a função DateSerial que passa anos, meses e dias em valores separados, a função DateValue exige o texto da data de ser de acordo com um dos padrões aceitos definidos para sua região (veja - Configurações de idioma - Idioma) ou a um formato ISO de data (momentaneamente, somente datas com hifens, por exemplo, "2012-12-31" são aceitos).

Valor de retorno:

A data calculada.

Exemplo:


    dt = svc.DateValue("23-02-2011")
    print(dt)
  

Format

Converte um número em um string e formata-a de acordo com a formatação especificada.

Sintaxe:

svc.Format(expression: any, format = ''): str

Parâmetros:

expression: Expressão numérica que você deseja converter em uma string formatada.

format: Caractere que especifica o código de formato do número. Se format for omitido, a função Formatar funciona como a função LibreOffice Basic Str().

Valor de retorno:

Caractere texto.

Códigos de formatação

A lista a seguir descreve os códigos que você pode usar para formatar uma expressão numérica:

0: se expressão tiver um dígito na posição do 0 no código formato, o dígito será exibido; do contrário, será exibido 0.

Se a expressão tiver menos dígitos que a quantidade de zeros no código format (em qualquer lado do decimal), serão exibidos zeros à esquerda ou à direita. Se a expressão tiver mais dígitos à esquerda do separador decimal do que o número de zeros no código format, os dígitos adicionais serão exibidos sem formatação.

As casas decimais na expressão são arredondadas de acordo com o número de zeros exibidos que aparecem após o separador decimal no código Format.

#: se Expressão contém um dígito na posição do espaço reservado para # no código Format, o dígito será exibido; do contrário, nada será exibido nesta posição.

Este símbolo funciona como o 0, exceto pelo fato de que os zeros à esquerda ou à direita não serão exibidos se houver mais caracteres # no código Format do que dígitos na Expressão. Serão exibidos apenas os dígitos relevantes do Expressão.

.: o espaço reservado para decimal determina o número de casas decimais à esquerda e à direita do separador decimal.

Se o código Format contiver somente espaços reservados para # à esquerda deste símbolo, os números menores que 1 começarão com um separador decimal. Para sempre exibir um zero à esquerda dos números fracionários, use o 0 como um marcador para o primeiro dígito à esquerda do separador decimal.

%: Multiplique a Expressão por 100 e insira o símbolo de porcentagem (%) onde a Expressão aparecer no código Format.

E- E+ e- e+ : Se o código Format contiver ao menos um marcador de posição de dígito (0 ou #) à direita do símbolo E-, E+, e- ou e+, a Expressão será exibida em um formato científico ou exponencial. A letra E ou e será inserida entre o número e o expoente. O número de marcadores de posição para dígitos à direita do símbolo determina o número de dígitos no expoente.

Se o expoente for negativo, o sinal de subtração será exibido diretamente antes de um expoente com E-, E+, e-, e+. Se o expoente for positivo, o sinal de adição só será exibido antes de expoentes com E+ ou e+.

O delimitador de milhares será exibido se o código Format exibir o delimitador entre marcadores de posição dos dígitos (0 ou #).

O uso do ponto como separador de milhares e de decimais é dependente das configurações regionais. Quando usar um número no código fonte Basic, sempre use um ponto como separador decimal. O caractere exibido como separador decimal depende no formato de número usado no seu sistema.

- + $ ( ) espaço: O sinal de adição (+), subtração (-), cifrão ($), espaço ou parênteses inserido diretamente no código Format será exibido com um caractere literal.

Para exibir caracteres diferentes dos listados aqui, você deve precedê-los de uma barra invertida (\) ou colocá-los entre aspas (" ").

\ : A barra invertida exibe o próximo caractere no código Format.

Os caracteres no código Format que tem um significado reservado só podem ser mostrados como caracteres literais se estiverem precedidos de uma barra invertida. A barra invertida não é exibida, a menos que você digite duas barras invertidas (\\) no código de formatação.

Os caracteres que devem ser precedidos de uma barra invertida no código de formato para serem exibidos como caracteres literais são: caracteres de formatação de data e hora (a, c, d, h, m, n, p, q, s, t, w, y, /, :), caracteres de formatação de números (#, 0, E, %, e, vírgula, ponto) e caracteres de formatação de cadeia de caracteres (@, &, <, >, !).

Você também pode usar os formatos de número predefinidos. Com exceção do "Número Geral", todos os códigos de formato predefinidos retornam o número como um número decimal com duas casas decimais.

Se você usar formatos predefinidos, o nome do formato deverá estar entre aspas.

Formatos pré-definidos

General Number: os números são exibidos da forma como são inseridos.

Currency: insere um sinal de cifrão na frente do número e coloca os números negativos entre parênteses.

Fixed: exibe pelo menos um dígito na frente do separador decimal.

Standard: exibe os números com um separador de milhar.

Percent: multiplica o número por 100 e acrescenta a ele um sinal de porcentagem.

Scientific: Exibe números no formato científico (por exemplo, 1.00E+03 for 1000).

Um código Format pode ser dividido em três seções separadas por ponto e vírgula. A primeira parte define o formato para valores positivos, a segunda para valores negativos e, a terceira, para zero. Se você especificar somente um código Format, ele será aplicado a todos os números.

Você pode definir o local utilizado para controlar o formato de números, datas e moedas no LibreOffice Basic em - Configurações de idioma - Idiomas. Nos códigos de formato do Basic, o ponto decimal (.) sempre será utilizado como espaço reservado para o separador decimal em seu local e será substituído pelo caractere correspondente.

O mesmo se aplica para as configurações de locale para data, hora e formatos monetários. O código de formatação do Basic será interpretado e exibido de acordo com suas configurações de locale.

Exemplo:


    txt = svc.Format(6328.2, '##.##0.00')
    print(txt)
  

GetDefaultContext

Retorna o contexto padrão do "process service factory", se existente, ou retorna uma referência nula.

GetDefaultContext é uma alternativa ao método getComponentContext() disponível a partir da variável global XSCRIPTCONTEXT ou no módulo uno.py.

Sintaxe:

svc.GetDefaultContext(): uno

Valor de retorno:

O contexto padrão do componente é usado ao instanciar serviços usando o XMultiServiceFactory. Consulte o capítulo Professional UNO no Guia do Desenvolvedor pelo link api.libreoffice.org para maiores informações.

Exemplo:


    ctx = svc.GetDefaultContext()
  

GetGuiType

Retorna um valor numérico que especifica a interface gráfica do usuário. Esta função existe apenas por razões de compatibilidade com versões mais antigas.

Consulte o método system() do módulo Python platform para identificar o sistema operacional.

Sintaxe:

svc.GetGuiType(): int

Exemplo:


    n = svc.GetGuiType()
  

GetPathSeparator

Retorna o separador de diretórios dependente do sistema operacional usado para especificar caminhos de arquivos.

Use o método os.pathsep do módulo Python os para identificar o separador de diretórios.

Sintaxe:

svc.GetPathSeparator(): str


    svc.GetPathSeparator(): str
  

Exemplo:


    sep = svc.GetPathSeparator()
  

GetSystemTicks

Retorna o número de tiques do sistema fornecido pelo sistema operacional. Você pode utilizar esta função para otimizar certos processos. Use este método para estimar tempos em milissegundos.

Sintaxe:

svc.GetSystemTicks(): int

Exemplo:


    ticks_ini = svc.GetSystemTicks()
    time.sleep(1)
    ticks_end = svc.GetSystemTicks()
    svc.MsgBox("{} - {} = {}".format(ticks_end, ticks_ini,ticks_end - ticks_ini))
  

GlobalScope.BasicLibraries

Retorna o objeto UNO contendo todas as bibliotecas e módulos Basic compartilhados.

Este método é o equivalente em Python à instrução GlobalScope.BasicLibraries em scripts Basic.

Sintaxe:

svc.GlobalScope.BasicLibraries(): uno

Valor de retorno:

com.sun.star.script.XLibraryContainer

Exemplo:

O exemplo a seguir carrega a biblioteca Basic Gimmicks se ela ainda não tiver sido carregada.


    libs = svc.GlobalScope.BasicLibraries()
    if not libs.isLibraryLoaded("Gimmicks"):
        libs.loadLibrary("Gimmicks")
  

GlobalScope.DialogLibraries

Retorna um objeto UNO contendo todas as bibliotecas de diálogo compartilhadas.

Este método é o equivalente em Python à instrução GlobalScope.DialogLibraries em scripts Basic.

Sintaxe:

svc.GlobalScope.DialogLibraries(): uno

Valor de retorno:

com.sun.star.comp.sfx2.DialogLibraryContainer

Exemplo:

Os exemplo a seguir mostram uma caixa de mensagem com os nomes de todas as bibliotecas de diálogo compartilhadas.


    dlg_libs = svc.GlobalScope.DialogLibraries()
    lib_names = dlg_libs.getElementNames()
    svc.MsgBox("\n".join(lib_names))
  

InputBox

Sintaxe:

svc.InputBox(prompt: str, [title: str], [default: str], [xpostwips: int, ypostwips: int]): str

Parâmetros:

prompt: expressão de cadeia de caracteres exibida como uma mensagem na caixa de diálogo.

title: expressão de cadeia de caracteres exibida na barra de título da caixa de diálogo.

default: expressão de cadeia de caracteres exibida como padrão na caixa de texto quando nenhuma outra entrada é fornecida.

xpostwips: expressão de número inteiro que especifica a posição horizontal da caixa de diálogo. A posição é uma coordenada absoluta e não faz referência à janela do LibreOffice.

ypostwips: expressão de número inteiro que especifica a posição vertical da caixa de diálogo. A posição é uma coordenada absoluta e não faz referência à janela do LibreOffice.

Se xpostwips e ypostwips forem omitidos, a caixa de diálogo será centralizada na tela. A posição é especificada em twips.

Valor de retorno:

cadeia de caracteres

Exemplo:


    txt = s.InputBox('Por favor, digite uma frase:', 'Prezado usuário')
    s.MsgBox(txt, MB_ICONINFORMATION, 'Confirmação da frase')
  
note

Para informações mais detalhadas consulte a página Wiki Input/Output to Screen with Python.


MsgBox

Mostra uma caixa de diálogo contendo uma mensagem e retorna um valor opcional.
Constantes MB_XX especificam o tipo da caixa de diálogo, o número e o tipo dos botões a serem mostrados, além do tipo do ícone. Ao adicionar seus respectivos valores eles formam padrões de bits que definem a aparência de um diálogo MsgBox.

Sintaxe:

svc.MsgBox(prompt: str, [buttons: int], [title: str])[: int]

Parâmetros:

prompt: Expressão de cadeia de caracteres exibida como uma mensagem na caixa de diálogo. Quebras de linha podem ser inseridas com Chr$(13).

title: expressão de cadeia de caracteres exibida na barra de título da caixa de diálogo. Se omitida, a barra de títulos exibe o nome do aplicativo correspondente.

buttons: qualquer expressão de número inteiro que especifique o tipo da caixa de diálogo, assim como o número e o tipo dos botões a serem exibidos e o tipo do ícone. buttons representa uma combinação de padrões de bits, ou seja, é possível definir uma combinação de elementos adicionando-se seus respectivos valores:

Valor de retorno:

Um valor inteiro opcional conforme detalhado anteriormente nas propriedades IDXX.

Exemplo:


    txt = s.InputBox('Por favor, digite uma frase:', 'Prezado usuário')
    s.MsgBox(txt, MB_ICONINFORMATION, 'Confirmação da frase')
  
note

Para informações mais detalhadas consulte a página Wiki Input/Output to Screen with Python.


Now

Retorna a data e hora corrente do sistema em um objeto nativo Python do tipo datetime.datetime.

Sintaxe:

svc.Now(): datetime

Exemplo:


    svc.MsgBox(svc.Now(), svc.MB_OK, "Now")
  

RGB

Retorna um valor inteiro representando uma cor, constituído pelos componentes vermelho, verde e azul.

Sintaxe:

svc.RGB(red:int, green: int, blue: int): int

Parâmetros:

red: qualquer expressão de número inteiro que represente o componente vermelho (0-255) da cor composta.

green: qualquer expressão de número inteiro que represente o componente verde (0-255) da cor composta.

blue: qualquer expressão de número inteiro que represente o componente azul (0-255) da cor composta.

tip

A caixa de diálogo Colher uma cor ajuda a calcular os componentes vermelho, azul e verde de uma cor composta. As caixas Cor do texto e Cores personalizadas mostram a caixa Colher uma cor.


Valor de retorno:

inteiro

Exemplo:


    YELLOW = svc.RGB(255,255,0)
  

ThisComponent

Se o componente atual é um documento LibreOffice, este método retorna o objeto UNO representando o documento.

Este método retorna None quando o componente atual não corresponde a um documento.

Sintaxe:

svc.ThisComponent(): uno

Exemplo:


    comp = svc.ThisComponent
    svc.MsgBox("\n".join(comp.getSupportedServiceNames()))
  

ThisDatabaseDocument

Se o script estiver sendo executado a partir de um documento Base ou um de seus subcomponentes este método retornará o componente principal da instância do Base.

Este método retorna None caso contrário.

Sintaxe:

svc.ThisDatabaseDocument(): uno

Exemplo:


    db_doc = svc.ThisDatabaseDocument
    table_names = db_doc.DataSource.getTables().getElementNames()
    bas.MsgBox("\n".join(table_names))
  
tip

Visite a página da documentação da API sobre o OfficeDatabaseDocument para aprender mais sobre a estrutura do componente principal de um documento Base.


Xray

Inspeciona objetos ou variáveis UNO.

Sintaxe:

svc.Xray(obj: any)

Parâmetros:

obj: Uma variável ou objeto UNO.

Exemplo:


    svc.Xray(svc.StarDesktop)
  
warning

Todas as rotinas básicas ou identificadores do ScriptForge que possuem o caractere "_" como prefixo são reservados apenas para uso interno. Elas não devem ser usadas em macros Basic.


♥ Doe para nosso projeto! ♥