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.

Exemplo típico:


   bas.MsgBox('Mostra este texto numa caixa de mensagem a partir de um script Python')

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

Invocação do serviço

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


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

Propriedades

Nome	Somente leitura	Tipo	Descrição
MB_OK, MB_OKCANCEL, MB_RETRYCANCEL, MB_YESNO, MB_YESNOCANCEL	Sim	Integer	Valores: 0, 1, 5, 4, 3
MB_ICONEXCLAMATION, MB_ICONINFORMATION, MB_ICONQUESTION, MB_ICONSTOP	Sim	Integer	Valores: 48, 64, 32, 16
MB_ABORTRETRYIGNORE, MB_DEFBUTTON1, MB_DEFBUTTON2, MB_DEFBUTTON3	Sim	Integer	Valores: 2, 128, 256, 512
IDABORT, IDCANCEL, IDIGNORE, IDNO, IDOK, IDRETRY, IDYES	Sim	Integer	Valores: 3, 2, 5, 7, 1, 4, 6 Constantes que indicam o botão selecionado em MsgBox.
StarDesktop	Sim	Objeto UNO	Retorna o objeto StarDesktop que representa o aplicativo LibreOffice.
ThisComponent	Sim	objeto UNO	Se o componente atual se referir a um documento LibreOffice, esse método retornará o objeto UNO que representa o documento. Esta propriedade retorna None quando o componente atual não corresponde a um documento.
ThisDatabaseDocument	Sim	objeto UNO	Se o script estiver sendo executado a partir de um documento Base ou qualquer um de seus subcomponentes, este método retorna o componente principal da instância Base. Caso contrário, esta propriedade retorna None.

Lista de Métodos no Serviço Basic
CDate CDateFromUnoDateTime CDateToUnoDateTime ConvertFromUrl ConvertToUrl CreateUnoService CreateUnoStruct DateAdd	DateDiff DatePart DateValue Format GetDefaultContext GetGuiType GetPathSeparator GetSystemTicks	GlobalScope.BasicLibraries GlobalScope.DialogLibraries InputBox MsgBox Now RGB Xray

CDate

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

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 - Idiomas e Localidades - Geral) 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 = bas.CDate(1000.25)
    bas.MsgBox(str(d)) # 1902-09-26 06:00:00
    bas.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.


    uno_date = bas.CreateUnoStruct('com.sun.star.util.DateTime')
    uno_date.Year = 1983
    uno_date.Month = 2
    uno_date.Day = 23
    new_date = bas.CDateFromUnoDateTime(uno_date)
    bas.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 = bas.CDateToUnoDateTime(current_datetime)
    bas.MsgBox(str(uno_date.Year) + "-" + str(uno_date.Month) + "-" + str(uno_date.Day))

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
yyyy	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: Um valor datetime.datetime especificado. O valor interval será acrescentado number vezes a este valor datetime.datetime.

Valor de retorno:

Um valor datetime.datetime.

Exemplo:


    dt = datetime.datetime(2004, 1, 31)
    dt = bas.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 um intervalo de data, conforme definido 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 = bas.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(bas.DatePart("ww", datetime.datetime(2005,12,31)
    print(bas.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:

data: String que contém a data que será convertida para um objeto Date.

A string a ser passada para a função DateValue deve ser expressa em um dos formatos de data definidos por suas configurações de localidade (veja suas configurações em - Idiomas e localidades - Geral) ou usando o formato ISO "yyyy-mm-dd" (ano, mês e dia separado por hifens).

Valor de retorno:

A data calculada.

Exemplo:


    dt = bas.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 - Idiomas e localidades - Geral. 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 localidade 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 localidade.

Exemplo:


    txt = bas.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 = bas.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 = bas.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

Exemplo:


    sep = bas.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 = bas.GetSystemTicks()
    time.sleep(1)
    ticks_end = bas.GetSystemTicks()
    bas.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 = bas.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 = bas.GlobalScope.DialogLibraries()
    lib_names = dlg_libs.getElementNames()
    bas.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:

String

Exemplo:


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

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:

bas.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, s.MB_ICONINFORMATION, "Confirmação da frase")

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:


    bas.MsgBox(bas.Now(), bas.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.

O valor resultante Long é calculado com a seguinte fórmula:
Resultado = red×65536 + green×256 + blue.

No modo de compatibilidade com o VBA (Option VBASupport 1), o valor Long é calculado como
Resultado = red + green×256 + blue×65536
Veja Função RGB [VBA]

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:

Integer

Exemplo:


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

Xray

Inspeciona objetos ou variáveis UNO.

Sintaxe:

svc.Xray(obj: any)

Parâmetros:

obj: Uma variável ou objeto UNO.

Exemplo:


    bas.Xray(bas.StarDesktop)

Todas as rotinas ou identificadores do ScriptForge em Basic que possuem o caractere "_" como prefixo são reservadas para uso interno. Elas não devem ser usadas em macros escritas em Basic ou em Python.

Especificador GlobalScope

Programando com scripts Python

uno.fileUrlToSystemPath()

uno.systemPathToFileUrl()

Input/Output to Screen with Python no Wiki

XSCRIPTCONTEXT.getComponentContext()

uno.getComponentContext()

platform.system()

os.pathsep()