Sumário

# Serviço ScriptForge.Exception

O serviço Exception fornece uma coleção de métodos que ajudam a depurar scripts em Basic e Python e também auxiliam na manipulação de exceções em scripts escritos em Basic.

Em scripts Basic, quando um erro de em tempo de execução ocorre, os métodos e propriedades do serviço Exception ajudam a identificar o contexto do erro e ajudam na sua manipulação.

- O serviço SF_Exception é semelhante ao objeto VBA Err.

- A propriedade Number identifica o erro.

- Utilize o método Raise para interromper o processamento. O método RaiseWarning pode ser usado para capturar uma anomalia sem interromper a execução da macro.

Erros e alertas lançados com o serviço Exception são armazenados em memória e podem ser recuperados usando o método Console.

O console do serviço Exception armazena eventos, valores de variáveis e informações sobre erros. Use o console quando a IDE Basic não estiver facilmente acessível, por exemplo em Funções definidas pelo usuário no Calc ou durante o processamento de eventos.

Use o método DebugPrint para adicionar informações relevantes ao console. As entradas do console podem ser salvas em arquivo texto ou visualizadas em uma janela de diálogo.

Quando um erro ocorre, uma macro de aplicação pode:

1. Reportar o erro no console Exception

2. Informar o usuário sobre o erro usando uma mensagem padrão ou uma mensagem customizada

3. Opcionalmente paralisar a execução

When an error is detected in a call to the ScriptForge API, the behaviour of the application is determined by specific properties:

1. Log the error in the Exception console. This is always done.

2. Inform the user about the error with either a standard or a localized message.

   To force a silent mode, set :

   exception.ReportScriptErrors = False ' Default = True

3. To not stop the execution of the current macro, set:

   exception.StopWhenError = False ' Default = True

   It then makes sense before further processing to explore the values of:

   exception.ReturnCode ' Short error description

   exception.ReturnCodeDescription ' Long error description

Em scripts Python o serviço Exception é usado principalmente para fins de depuração. Métodos como DebugPrint, Console e DebugDisplay são úteis para rapidamente imprimir mensagens, registrar dados e abrir a janela do console a partir de um script em Python.

Nem todos os métodos e propriedades estão disponíveis para scripts em Python, pois a linguagem Python já possui um sistema de manipulação de exceções bastante completo.

## Invocação do serviço

Antes de usar o serviço Exception, a biblioteca ScriptForge deve ser carregada ou importada:

• Macros BASIC precisam carregar a biblioteca ScriptForge usando a seguinte instrução:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Scripts Python exigem uma importação do módulo scriptforge:
from scriptforge import CreateScriptService

##### Em Basic

Os exemplos a seguir mostram três diferentes abordagens para chamar o método Raise. Todos os outros métodos podem ser executados de forma semelhante.

        SF_Exception.Raise(...)

        Dim exc : exc = SF_Exception
        exc.Raise(...)

        Dim exc : exc = CreateScriptService("Exception")
        exc.Raise(...)

##### Em Python

O trecho de código abaixo cria uma instância do serviço Exception, registra uma mensagem e mostra a janela do Console.

        from scriptforge import CreateScriptService
        exc = CreateScriptService("Exception")
        someVar = 100
        exc.DebugPrint("Value of someVar", someVar)
        exc.Console()

## Propriedades

The properties listed below are only available for Basic scripts. They are related to errors occurring in any macro statement.

Nome | Somente leitura | Descrição
--- | --- | ---
Description | Não | Texto da mensagem de erro. O valor padrão é "" ou uma string contendo a mensagem do erro de tempo de execução do Basic.
Number | Não | O código do erro. Pode ser numérico ou um texto. O valor padrão é 0 ou o valor numérico correspondente ao código do erro de tempo de execução Basic.
Source | Não | A localização de onde o erro ocorreu no código. Pode ser um valor numérico ou texto. O valor padrão é 0 ou a linha do código fonte onde o erro de tempo de execução Basic padrão ocorreu.

Lançar ou limpar um objeto Exception redefine suas propriedades.

O intervalo de códigos de erro de 0 a 200 é reservado para o LibreOffice Basic. Erros definidos pelo usuário podem começar com valores maiores para prevenir colisões com os desenvolvimentos futuros do LibreOffice Basic.

The properties listed below are available for Basic and Python scripts. They are related to errors detected by the ScriptForge API only.

Nome | Apenas leitura | Return type | Descrição
--- | --- | --- | ---
ReportScriptErrors | Não | Boleano | Indicates whether script errors are displayed in a message box when they occur. Default value is False.
ReturnCode | Sim | String | The code returned by the last call to the ScriptForge API from a user script. It is the zero-length string if everything ran without error.
ReturnCodeDescription | Sim | String | The description of the code returned by the last call to the ScriptForge API from a user script. It is the zero-length string if everything ran without error.
StopWhenError | Não | Boleano | Indicates whether the macro is stopped when ScriptForge detects a user script error.

Lista de métodos no serviço Exception
Clear Console ConsoleClear ConsoleToFile | DebugDisplay DebugPrint PythonPrint | PythonShell Raise RaiseWarning

## Clear

Redefine o estado do erro atual e limpa as propriedades de SF_Exception.

Este método só está disponível em scripts Basic.

### Sintaxe:

        SF_Exception.Clear()

### Exemplo:

O exemplo a seguir mostra como capturar uma exceção causada por uma divisão por zero, cujo código de erro é 11.

        Sub Example_Clear()
            Dim a, b, c
            On Local Error GoTo Catch
            Try:
                a = 10 : b = 0
                c = a / b
                '...
                Exit Sub
            Catch:
                If SF_Exception.Number = 11 Then SF_Exception.Clear()
                'Se for divisão por zero, ignora o erro
        End Sub

Para uma lista completa de erros de tempo de execução Basic, consulte a página Depurar um programa Basic.

## Console

Mostra o console de mensagens em uma caixa de diálogo modal ou não modal. Em ambos os modos, todas as mensagens lançadas com o método DebugPrint() ou que resultaram de uma exceção são apresentadas. Caso a opção não modal seja escolhida, entradas subsequentes são adicionadas automaticamente.

Se o console já estiver aberto e a caixa de diálogo for não modal, ela é trazida para o primeiro plano.

Um console modal pode apenas ser fechado pelo usuário. Um console não modal pode ser fechado pelo usuário ou no momento do término da execução da macro.

### Sintaxe:

exc.Console(modal: bool = True)

### Parâmetros:

modal: Determina se a janela do console é modal (True) ou não modal (False). O valor padrão é True.

### Exemplo:

##### Em Basic

            SF_Exception.Console(Modal := False)

##### Em Python

        exc.Console(modal = False)

## ConsoleClear

Limpa o console mantendo uma quantidade opcional de mensagens mais recentes. Se o console é ativado como não modal, ele é atualizado.

### Sintaxe:

exc.ConsoleClear(keep: int = 0)

### Parâmetros:

keep: Número de mensagens recentes a serem mantidas. O valor padrão é 0.

### Exemplo:

O exemplo a seguir limpa o console mantendo as 10 mensagens mais recentes.

##### Em Basic

            SF_Exception.ConsoleClear(10)

##### Em Python

        exc.ConsoleClear(10)

## ConsoleToFile

Exporta os conteúdos do console para um arquivo de texto. Se o arquivo já existe e o console não estiver vazio, o arquivo será sobrescrito sem aviso prévio. Retorna True se bem-sucedido.

### Sintaxe:

exc.ConsoleToFile(filename: str): bool

### Parâmetros:

filename: Nome do arquivo texto para salvar os conteúdos do console. O nome é expresso conforme o valor atual da propriedade FileNaming do serviço SF_FileSystem. Por padrão, tanto a Notação URL como o formato nativo do sistema operacional são admissíveis.

### Exemplo:

##### Em Basic

            SF_Exception.ConsoleToFile("C:\Documents\myFile.txt")

##### Em Python

        exc.ConsoleToFile(r"C:\Documents\myFile.txt")

## DebugDisplay

Concatena todos os argumentos em uma única string legível por humanos e mostra-a em um MsgBox com um ícone de Informação e um botão OK.

A string final também é adicionada ao Console.

### Sintaxe:

exc.DebugDisplay(arg0: any, [arg1: any, ...])

### Parâmetros:

arg0[, arg1, ...]: Qualquer quantidade de argumentos, de qualquer tipo.

### Exemplo:

##### Em Basic

        SF_Exception.DebugDisplay("Current Value", someVar)

##### Em Python

        exc.DebugDisplay("Current Value", someVar)

## DebugPrint

Combina todos os argumentos em uma única string legível e adiciona-a como uma nova entrada no console.

### Sintaxe:

exc.DebugPrint(arg0: any, [arg1: any, ...])

### Parâmetros:

arg0[, arg1, ...]: Qualquer quantidade de argumentos, de qualquer tipo.

### Exemplo:

##### Em Basic

        SF_Exception.DebugPrint(Null, Array(1, 2, 3), "line1" & Chr(10) & "Line2", DateSerial(2020, 04, 09))
        ' [NULL]   [ARRAY] (0:2) (1, 2, 3)  line1\nLine2  2020-04-09

##### Em Python

        exc.DebugPrint(None, [1, 2, 3], "line1\nline2")
        # None  [1, 2, 3]  line1\nline2

## PythonPrint

Exibe a lista de argumentos de forma legível no console da plataforma. Os argumentos são separados por um caractere TAB (simulado por espaços).

A mesma string é adicionada ao console de depuração do ScriptForge.

Se shell Python (APSO) estiver ativo, o conteúdo de PythonPrint é gravado no console APSO no lugar do console da plataforma.

Este método só está disponível em scripts Basic.

### Sintaxe:

      exc.PythonPrint(arg0: any, [arg1: any, ...])

### Parâmetros:

arg0[, arg1, ...]: Qualquer quantia de argumentos de qualquer tipo. O comprimento máximo de cada argumento individual é 1024 caracteres.

### Exemplo:

        exc.PythonPrint(a, Array(1, 2, 3), , "line1" & Chr(10) & "Line2", DateSerial(2020, 04, 09))

Em Python, use uma instrução print para imprimir no console APSO ou use o método DebugPrint para imprimir no console do ScriptForge.

## PythonShell

Abre o shell Python APSO em uma janela não modal. O script Python continua sendo executado após o shell tiver sido aberto. As saídas de instruções print dentro do script também são apresentadas no shell.

Apenas uma única instância do shell Python APSO pode estar aberta ao mesmo tempo. Logo, se um shell Python já estiver aberto, então uma chamada deste método não terá efeito algum.

Esse método requer a instalação da extensão APSO (organizador de script alternativo para Python) . Por sua vez, APSO requer a presença de um framework de script LibreOffice Python. Se APSO ou Python não existirem, ocorrerá um erro.

### Sintaxe:

exc.PythonShell(opt variables: dict, background = 0xFDF6E3, foreground = 0x657B83)

### Parâmetros:

variables: um dicionário Python com nomes de variáveis e valores que serão passados para o shell Python APSO. Por padrão todas as variáveis locais são passadas usando a função interna do Python locals().

Plano de fundo: cor do plano de fundo do console especificada como valor inteiro RGB de 24 bits. O plano de fundo padrão é o do APSO.

Plano frontal: cor do plano frontal do console especificada como valor inteiro RGB de 24 bits. O plano frontal padrão é o do APSO.

### Exemplo:

O exemplo abaixo abre o shell Python do APSO e passa todas as variáveis globais e locais, considerando o contexto no qual o script está executando. O console é exibido com caracteres brancos em um plano de fundo preto.

        exc.PythonShell({**globals(), **locals()}, \
            background = 0x0, foreground = 0xFFFFFF)

Quando o shell Python APSO estiver aberto, quaisquer valores impressos pelo script serão mostrados no shell. Assim, a string impressa no exemplo abaixo será mostrada no shell Python.

        s = CreateScriptService('Basic')
        RED, BLUE = s.RGB(255,0,0), s.RGB(0,0,255)
        exc.PythonShell(background=RED, foreground=BLUE)
        print("Olá Mundo!")

## Raise

Gera um erro de tempo de execução. Uma mensagem de erro é apresentada ao usuário e registrada no console. A execução é paralisada. O método Raise() pode ser colocado dentro do fluxo normal de um script ou em uma sub-rotina dedicada ao manuseio do erro.

Este método só está disponível em scripts Basic.

### Sintaxe:

        SF_Exception.Raise(Number := Err, [Source := Erl], [Description := Error$])

Os trechos de código a seguir são equivalentes. Eles mostram maneiras alternativas de lançar uma exceção com código 2100.

        SF_Exception.Raise(2100)

        SF_Exception.Number = 2100
        SF_Exception.Raise()

        SF_Exception.Raise Number := 2100

### Parâmetros:

Number: o código de erro, como número ou string. O valor padrão é àquele da função Basic interna Err, e neste caso Number é opcional.

O intervalo de códigos de erro de 0 a 200 é reservado para o LibreOffice Basic. Erros definidos pelo usuário podem começar com valores maiores para prevenir colisões com os desenvolvimentos futuros do LibreOffice Basic.

Source: Localização do erro, como um valor numérico ou uma string. O valor padrão é o fornecido pela função interna do Basic Erl.

Description: Mensagem a ser apresentada ao usuário e registrada no console. O valor padrão é o fornecido pela função interna do Basic Error$.

### Exemplo:

        Sub Example_Raise()
            Dim a, b, c
            On Local Error GoTo Catch
            Try:
                a = 10 : b = 0
                c = a / b
                '...
                Exit Sub
            Catch:
                'Veja as variantes abaixo...
        End Sub

Para lançar uma exceção com os valores padrão:

        Catch:
            SF_Exception.Raise()

Para lançar uma exceção com um código de erro específico:

        Catch:
            SF_Exception.Raise(11)

Para substituir a mensagem de erro usual:

        Catch:
            SF_Exception.Raise(, , "Não é uma boa ideia dividir por zero.")

Para lançar um erro de aplicação:

        Catch:
            SF_Exception.Raise("MyAppError", "Example_Raise()", "Algo errado aconteceu!")

## RaiseWarning

Este método tem exatamente a mesma sintaxe, argumentos e comportamento do método Raise().

Contudo, quando um alerta é lançado, a execução da macro não é paralisada..

Este método só está disponível em scripts Basic.

### Sintaxe:

        SF_Exception.RaiseWarning([Number As Variant], [Source As Variant], [Description As String])

### Parâmetros:

Number: o código de erro, como número ou string. O valor padrão é àquele da função Basic interna Err, e neste caso Number é opcional.

O intervalo de códigos de erro de 0 a 200 é reservado para o LibreOffice Basic. Erros definidos pelo usuário podem começar com valores maiores para prevenir colisões com os desenvolvimentos futuros do LibreOffice Basic.

Source: Localização do erro, como um valor numérico ou uma string. O valor padrão é o fornecido pela função interna do Basic Erl.

Description: Mensagem a ser apresentada ao usuário e registrada no console. O valor padrão é o fornecido pela função interna do Basic Error$.

### Exemplo:

        SF_Exception.RaiseWarning(Source:="Example_Raise()", _
            Description:="Ocorreu algo de errado !", _
            Number:="MeuAppDeErro")

Tópicos relacionados

Funções de manipulação de erros

♥ Doe para nosso projeto! ♥