Conteúdo

# Utilização de procedimentos, funções e propriedades

A seguir, descreve-se a utilização básica de procedimentos, funções e propriedades no LibreOffice Basic.

Quando cria um novo módulo, o LibreOffice Basic insere automaticamente uma rotina Sub chamada "Main". Este nome predefinido não tem qualquer relação com a ordem ou o ponto de partida de um projeto LibreOffice Basic. Pode também renomear esta rotina Sub sem qualquer problema.

Existem algumas restrições quanto aos nomes das suas variáveis públicas, sub-rotinas, funções e propriedades. Não deve utilizar o mesmo nome que um dos módulos da mesma biblioteca.

Os procedimentos (Subroutines), as funções (Function) e as propriedades (Property) ajudam a manter uma visão geral estruturada, dividindo um programa em partes lógicas. Estas partes podem ser facilmente reutilizadas para realizar tarefas semelhantes noutros projetos.

## Passagem de variáveis para procedimentos, funções ou propriedades

É possível passar variáveis tanto para procedimentos como para funções ou propriedades. O Sub, a Function ou a Property devem ser declarados de forma a aceitar parâmetros:

      Sub SubName(Parameter1 As TYPENAME, Parameter2 As TYPENAME,...)
          ' o seu código vai aqui
      End Sub

O Sub é chamado utilizando a seguinte sintaxe:

      [Call] SubName( [Parameter1:=]Value1, [Parameter2:=]Value2, ...)

Os parâmetros passados a uma Sub devem corresponder aos especificados na declaração da Sub.

O mesmo processo aplica-se a uma Função. Além disso, as funções devolvem sempre um resultado. Este resultado é definido atribuindo o valor a devolver ao nome da função:

      Function FunctionName(Parameter1 As TYPENAME, Parameter2 As TYPENAME,...) As TYPENAME
          ' o seu código vai aqui
          FunctionName=Result
      End Function

A função é chamada utilizando a seguinte sintaxe:

      Variable = FunctionName( [Parameter1:=]Value1, [Parameter2:=]Value2, ...)

As propriedades combinam a sintaxe dos procedimentos e das funções. Uma Propriedade requer normalmente até um parâmetro.

      Private _IsApproved As TYPENAME
      Property Get IsApproved As TYPENAME
          ' o seu código vai aqui
          IsApproved = some_computation
      End Property
      Property Let IsApproved(value As TYPENAME)
          ' o seu código vai aqui
          _IsApproved = computed_value
      End Property

A Propriedade é chamada utilizando a seguinte sintaxe:

      var = IsApproved
      IsApproved = some_value

Também pode utilizar o nome completo para chamar um procedimento, função ou propriedade:
[Call] Library.Module.Macro(), em que Call é opcional.
Por exemplo, para chamar a macro Autotext da biblioteca Gimmicks, utilize o seguinte comando:
Gimmicks.AutoText.Main()

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

Os parâmetros podem ser passados para um procedimento, uma função ou uma propriedade por referência ou por valor. Salvo indicação em contrário, um parâmetro é sempre passado por referência. Isso significa que um Sub, uma Function ou uma Property recebe o parâmetro e pode ler e modificar o seu valor.

Se pretender passar um parâmetro por valor, insira a palavra-chave ByVal à frente do parâmetro ao chamar uma Sub, uma Function ou uma Property, por exemplo:

      Function ReadOnlyParms(ByVal p2, ByVal p2)
          ' o seu código vai aqui
      End Function
      result = ReadOnlyParms(parm1, parm2)

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

## Definição de parâmetros opcionais

As funções, os procedimentos ou as propriedades podem ser definidos com parâmetros opcionais, por exemplo:

      Sub Rounding(number, Optional decimals, Optional format)
          ' o seu código vai aqui
      End Sub

## Positional or Keyword Arguments

Quando se chama uma função ou uma sub-rotina, é possível passar os seus argumentos por posição ou por nome. Passar por posição significa simplesmente listar os argumentos na ordem em que os parâmetros estão definidos na função ou sub-rotina. A passagem por nome requer que se anteponha ao argumento o nome do parâmetro correspondente, seguido de dois pontos e um sinal de igual (:=). Os argumentos-chave podem aparecer em qualquer ordem. Consulte a função Replace() básica para ver exemplos.

Quando for necessário passar menos parâmetros, utilize argumentos por palavra-chave. Passar valores para menos parâmetros por posição obriga a fornecer valores para todos os parâmetros que os precedem, sejam eles opcionais ou não. Isto garante que os valores se encontram nas posições corretas. Se passar os parâmetros por nome — utilizando argumentos por palavra-chave —, pode omitir todos os outros argumentos intermédios.

## Âmbito das variáveis

Uma variável definida dentro de um Sub, uma Function ou uma Property permanece válida apenas até à saída do procedimento. Esta é conhecida como variável «local». Em muitos casos, é necessário que uma variável seja válida em todos os procedimentos, em todos os módulos de todas as bibliotecas, ou após a saída de um Sub, um Function ou um Property.

### Declarar variáveis fora de um Sub, de uma Função ou de uma Propriedade

    Global VarName As TYPENAME

A variável é válida enquanto durar a sessão 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

Força as variáveis privadas a permanecerem privadas entre módulos, definindo 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 aciona um erro para Option Explicit)
          Print "Agora no módulo2 : ", myText
      End Sub

### Guardar conteúdo variável após sair de uma Sub, uma Função ou uma Propriedade

      Static VarName As TYPENAME

A variável mantém o seu valor até à próxima vez que for introduzida uma Function, Sub ou Property. A declaração deve estar dentro de uma Sub, uma Function ou uma Property.

## Especificar o tipo de valor de retorno de uma função ou de uma propriedade

Tal como acontece com as variáveis, inclua um caractere de declaração de tipo após o nome da função, ou o tipo indicado por As e o tipo de dados correspondente no final da lista de parâmetros para definir o tipo do valor de retorno da função ou propriedade, por exemplo:

      Function WordCount(WordText As String) As Integer

Tópicos relacionados

CompatibilityMode() Function

Instrução Option Explicit

Palavra-chave opcional

Declaração de Propriedade

Declaração estática

Necessitamos da sua ajuda!