Serviço.ScriptForge Basic

O serviço ScriptForge.Basic disponibiliza um conjunto de métodos LibreOffice Basic para serem executados num contexto Python. Os métodos do serviço Basic reproduzem exatamente a sintaxe e o comportamento das funções integradas do Basic.

Exemplo típico:

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

O serviço ScriptForge.Basic está limitado a scripts em Python.

Chamada de serviço

Antes de utilizar o serviço Basic, importe o método CreateScriptService() do módulo scriptforge:

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

Propriedades

Existem alternativas em Python para os métodos assinalados com (*).

CDate

Converte uma expressão numérica ou uma cadeia de caracteres num objeto nativo do Python do tipo datetime.datetime.

Este método disponibiliza a função incorporada do Basic CDate para scripts Python.

svc.CDate(expression: any): obj

expression: uma expressão numérica ou uma cadeia de caracteres que representa uma data.

    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/hora do UNO num objeto nativo do Python do tipo datetime.datetime.

svc.CDateFromUnoDateTime(unodate: uno): obj

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

O exemplo seguinte cria um objeto com.sun.star.util.DateTime e converte-o num objeto Python 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 num objeto com.sun.star.util.DateTime.

svc.CDateToUnoDateTime(date: obj): uno

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

    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))
  

ConvertFromUrl

Devolve um nome de ficheiro com o caminho do sistema para o URL file: indicado.

svc.ConvertFromUrl(url: str): str

url: Um URL file: absoluto.

Um nome de ficheiro no caminho do sistema.

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

O módulo uno O método fileUrlToSystemPath() devolve um caminho do sistema utilizando uma sintaxe idêntica.

    import uno
    filename = uno.fileUrlToSystemPath( "file:///C:/Program%20Files%20(x86)/LibreOffice/News.txt" )
    bas.MsgBox(filename)
  

ConvertToUrl

Devolve um URL file: para o caminho de sistema indicado.

svc.ConvertToUrl(systempath: str): str

systempath: Um nome de ficheiro do sistema na forma de uma cadeia de caracteres.

Um URL file: na forma de uma cadeia de caracteres.

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

O método systemPathToFileUrl() do módulo uno devolve um URL de ficheiro para o caminho de sistema indicado.

    from uno import systemPathToFileUrl as ConvertToUrl
    filename = ConvertToUrl( 'C:\Program Files(x86)\LibreOffice\News.txt' )
    bas.MsgBox(filename)
  

CreateUnoService

Instancia um serviço UNO com o ProcessServiceManager.

svc.CreateUnoService(servicename: str): uno

servicename: Um nome de serviço totalmente qualificado, como com.sun.star.ui.dialogs.FilePicker ou com.sun.star.sheet.FunctionAccess.

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

CreateUnoStruct

Devolve uma instância de uma estrutura UNO do tipo especificado.

svc.CreateUnoStruct(unostructure: str): uno

unostrutura: Um nome de estrutura totalmente qualificado, como com.sun.star.beans.Property ou com.sun.star.util.DateTime.

    date_struct = CreateUnoStruct('com.sun.star.util.DateTime')
  

módulo Uno O método createUnoStruct() cria uma instância de um tipo de estrutura Uno.

    import uno
    p = uno.createUnoStruct( 'com.sun.star.beans.Property' )
    bas.MsgBox(p)
  

DateAdd

Adiciona um intervalo de tempo a uma determinada data/hora um determinado número de vezes e devolve a data resultante.

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

interval: Uma expressão de cadeia de caracteres da tabela seguinte, que especifica o intervalo de data ou hora.

number: Uma expressão numérica que especifica com que frequência o valor do interval será somado, se for positivo, ou subtraído, se for negativo.

data: Um determinado valor datetime.datetime; o valor interval será adicionado number vezes a este valor datetime.datetime.

Um valor datetime.datetime.

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

DateDiff

Devolve o número de intervalos de data ou hora entre dois valores de data/hora especificados.

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

interval: Uma expressão de cadeia de caracteres que especifica o intervalo de datas, conforme detalhado no método DateAdd acima.

date1, date2: Os dois valores datetime.datetime a comparar.

Um número.

    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 devolve uma parte específica de uma data.

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

interval: Uma expressão de cadeia de caracteres que especifica o intervalo de datas, conforme detalhado no método DateAdd acima.

date: A data e hora a partir da qual o resultado é calculado.

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

A parte extraída para a data/hora indicada.

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

DateValue

Calcula um valor de data a partir de uma cadeia de caracteres de data.

svc.DateValue(date: str): datetime

data: Uma cadeia de caracteres que contém a data que será convertida num objeto Date.

A cadeia de caracteres passada para DateValue deve ser expressa num dos formatos de data definidos pela sua configuração de localização (ver - Idiomas e configurações regionais - Geral) ou utilizando o formato de data ISO «aaaa-mm-dd» (ano, mês e dia separados por hífens).

A data calculada.

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

Format

Converte um número numa cadeia de caracteres e, em seguida, formata-o de acordo com o formato que especificar.

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

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

GetDefaultContext

Devolve o contexto predefinido da fábrica de serviços do processo, se existir; caso contrário, devolve uma referência nula.

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

svc.GetDefaultContext(): uno

É utilizado o contexto de componente predefinido ao instanciar serviços através de XMultiServiceFactory. Consulte o capítulo Professional UNO no Guia do Desenvolvedor em api.libreoffice.org para obter mais informações.

    ctx = bas.GetDefaultContext()
  

GetGuiType

Devolve um valor numérico que especifica a interface gráfica do utilizador. Esta função é fornecida apenas para garantir a compatibilidade com versões anteriores.

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

svc.GetGuiType(): int

    n = bas.GetGuiType()
  

Estão disponíveis instruções mais detalhadas sobre o script na página de ajuda Identificar o sistema operativo.

• O serviço ScriptForge.Platform fornece um conjunto de propriedades sobre o ambiente e o contexto de execução atuais, incluindo a deteção da plataforma.

• Está disponível uma identificação abrangente do nome do sistema operativo através da fórmula de cálculo INFO("system").

GetPathSeparator

Devolve o separador de diretórios específico do sistema operativo utilizado para especificar os caminhos dos ficheiros.

Utilize os.pathsep do módulo os do Python para identificar o separador de caminho.

svc.GetPathSeparator(): str

    sep = bas.GetPathSeparator()
  

GetSystemTicks

Devolve o número de ticks do sistema fornecidos pelo sistema operativo. Pode utilizar esta função para otimizar determinados processos. Utilize este método para estimar o tempo em milissegundos:

svc.GetSystemTicks(): int

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

GlobalScope.BasicLibraries

Devolve o objeto UNO que contém todas as bibliotecas e módulos Basic partilhados.

Este método é o equivalente em Python a GlobalScope.BasicLibraries nos scripts Basic.

svc.GlobalScope.BasicLibraries(): uno

com.sun.star.script.XLibraryContainer

O exemplo seguinte carrega a biblioteca Gimmicks Basic, caso ainda não tenha sido carregada.

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

GlobalScope.DialogLibraries

Devolve o objeto UNO que contém todas as bibliotecas de diálogos partilhadas.

Este método é o equivalente em Python a GlobalScope.DialogLibraries nos scripts Basic.

svc.GlobalScope.DialogLibraries(): uno

com.sun.star.comp.sfx2.DialogLibraryContainer

O exemplo seguinte mostra uma caixa de mensagem com os nomes de todas as bibliotecas de diálogos disponíveis.

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

InputBox

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

String

    txt = s.InputBox('Introduza uma frase:', "Caro utilizador")
    s.MsgBox(txt, s.MB_ICONINFORMATION, "Confirmação da frase")
  

Para obter informações mais detalhadas, consulte Entrada/Saída para o ecrã com Python na Wiki.

MsgBox

Exibe uma caixa de diálogo com uma mensagem e devolve um valor opcional.
As constantes MB_xx ajudam a especificar o tipo de caixa de diálogo, o número e o tipo de botões a exibir, bem como o tipo de ícone. Ao somar os seus respetivos valores, formam padrões de bits que definem a aparência da caixa de diálogo MsgBox.

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

Um número inteiro opcional, conforme descrito nas propriedades IDxx acima.

    txt = s.InputBox('Introduza uma frase:', "Caro utilizador")
    s.MsgBox(txt, s.MB_ICONINFORMATION, "Confirmação da frase")
  

Para obter informações mais detalhadas, consulte Entrada/Saída para o ecrã com Python na Wiki.

Now

Devolve a data e a hora atuais do sistema como um objeto nativo do Python do tipo datetime.datetime.

svc.Now(): datetime

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

RGB

Devolve um valor de cor inteiro composto pelos componentes vermelho, verde e azul.

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

vermelho: Qualquer expressão numérica que represente a componente vermelha (0-255) da cor composta.

verde: Qualquer expressão numérica que represente a componente verde (0-255) da cor composta.

azul: Qualquer expressão numérica que represente a componente azul (0-255) da cor composta.

O valor Long resultante é calculado através da seguinte fórmula:
Resultado = vermelho×65536 + verde×256 + azul.

No modo de compatibilidade VBA (Option VBASupport 1), o valor Long é calculado como
Resultado = vermelho + verde×256 + azul×65536
Consulte Função RGB [VBA]

Português A caixa de diálogo do seletor de cores ajuda a calcular os componentes de vermelho, verde e azul de uma cor composta. Ao alterar a cor do texto e selecionar Cor personalizada, é apresentada a caixa de diálogo do seletor de cores.

Integer

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

Xray

Inspecionar objetos ou variáveis do Uno.

svc.Xray(obj: any)

obj: Uma variável ou um objeto UNO.

    bas.Xray(bas.StarDesktop)
  

Todas as rotinas ou identificadores do ScriptForge Basic que tenham o caractere de sublinhado «_» como prefixo estão reservados para uso interno. Não se destinam a ser utilizados em macros do Basic ou em scripts Python.