Módulo
Conteúdo
Índice 🔎︎

# Utilizar procedimentos e funções

O texto seguinte descreve a utilização básica de procedimentos e funções no LibreOffice Basic.

Ao criar um novo módulo, o LibreOffice Basic insere automaticamente uma SUB denominada "Main". Este nome padrão não tem qualquer relação com a ordem ou ponto de partida de um projeto do LibreOffice Basic. Pode também mudar o nome desta SUB em segurança.

Aplicam-se algumas restrições aos números de variáveis públicas, subs, e funções. Não se deve usar o mesmo nome que outro módulo da mesma biblioteca.

Os procedimentos (SUBS) e funções (FUNÇÕES) ajudam a manter uma síntese estruturada dividindo o programa em partes lógicas.

Um dos benefícios dos procedimentos e funções é que, assim que tiver criado um código de programa que contenha componentes de tarefas, pode utilizar este código noutro projeto.

## Transferir variáveis para procedimentos (SUB) e funções (FUNCTION)

As variáveis podem ser transferidas tanto para os procedimentos como para as funções. Terá de ser definida uma SUB ou uma FUNCTION para se obter os parâmetros:

    Sub SubName(Parameter1 As Type, Parameter2 As Type,...)

    Código do programa

    End Sub

A SUB é invocada utilizando a seguinte sintaxe:

    SubName(Value1, Value2,...)

Os parâmetros passados para uma SUB têm de corresponder aos especificados na declaração SUB.

O mesmo processo é aplicável às FUNÇÕES. Além do que foi referido, as funções devolvem sempre um resultado. O resultado de uma função é definido atribuindo o valor de retorno ao nome da função:

    Function FunctionName(Parameter1 As Type, Parameter2 As Type,...) As Type

    Código do programa

    NomeFunção=Resultado

    End Function

A FUNÇÃO é invocada utilizando a seguinte sintaxe:

    Variável=FunctionName(Parâmetro1, Parâmetro2,...)

Também pode utilizar o nome totalmente qualificado para invocar um procedimento ou função:
Library.Module.Macro()
Por exemplo, para invocar a macro Texto automático a partir da biblioteca Gimmicks, utilize o seguinte comando:
Gimmicks.AutoText.Main()

## Passar variáveis por referência ou valor

Os parâmetros podem ser transferidos para uma SUB ou FUNCTION tanto por referência como por valor. Salvo especificação em contrário, um parâmetro é sempre transferido por referência. Isso significa que uma SUB ou uma FUNCTION controla o parâmetro e pode ler e modificar o seu valor.

Se quiser enviar um parâmetro por valor, introduza a palavra-chave "ByVal" à frente do parâmetro, ao invocar uma SUB ou uma FUNCTION, como por exemplo:

    Result = Function(ByVal)

Neste caso, o conteúdo original do parâmetro não será alterado pela FUNCTION , uma vez que só obtém o valor e não o próprio parâmetro.

## Âmbito das variáveis

Uma variável definida numa SUB ou numa FUNCTION, só permanece válida até que se saia do procedimento. Esta variável é denominada de "local". Em muitos casos, é necessário que exista uma variável válida em todos os procedimentos, em todos os módulos de todas as bibliotecas ou depois de se sair de uma SUB ou de uma FUNCTION.

### Declarar variáveis fora de uma SUB ou de uma FUNCTION

    Global VarName As TYPENAME

A variável é válida durante toda a sessão do LibreOffice.

    Public VarName As TYPENAME

A variável é válida em todos os módulos.

    Private VarName As TYPENAME

A variável só é válida neste módulo.

    Dim VarName As TYPENAME

A variável só é válida neste módulo.

### Exemplo de variáveis privadas

Force as variáveis privadas a manterem-se privadas entre módulos ao definir CompatibilityMode(true).

    ' ***** Module1 *****

    Private myText As String

    Sub initMyText

        myText = "Olá"

        Print "No módulo1 : ", myText

    End Sub

    ' ***** Module2 *****

    'Option Explicit

    Sub demoBug

        CompatibilityMode( true )

        initMyText

        ' Agora devolve uma cadeia vazia

        ' (ou aumenta o erro para Option Explicit)

        Print "Agora no módulo2 : ", myText

    End Sub

### Guardar o conteúdo de uma variável depois de sair de uma SUB ou FUNCTION

    Static VarName As TYPENAME

A variável retém o seu valor até à próxima vez que a FUNÇÃO ou a SUB for executada. A declaração tem de existir dentro de uma SUB ou de uma FUNÇÃO.

## Especificar o Tipo de valor de retorno de uma FUNÇÃO

Tal como no caso das variáveis, tem que incluir um carácter de declaração de tipo depois do nome da função ou o tipo indicado por "As" e a correspondente palavra-chave no final da lista de parâmetros para definir o tipo de valor de retorno correspondente à função, como por exemplo:

    Function WordCount(WordText As String) As Integer