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