Uso di procedure, funzioni e proprietà

Viene descritto di seguito l'utilizzo di base delle procedure, delle funzioni e delle proprietà in LibreOffice Basic.

Quando si crea un nuovo modulo, LibreOffice Basic inserisce automaticamente una Sub denominata "Main". Questo nome predefinito non ha nulla a che vedere con l'ordine o il punto di partenza di un progetto LibreOffice Basic. È possibile rinominare senza problemi questa Subroutine.

Ai nomi delle variabili, subroutine, funzioni e proprietà pubbliche si applicano alcune restrizioni È vietato usare lo stesso nome utilizzato come nome di uno dei moduli della stessa libreria.

Procedure (Subroutine), funzioni (Function) e proprietà (Property) aiutano a mantenere una visione strutturata separando un programma in parti logiche. Queste parti possono essere facilmente riutilizzate per eseguire compiti simili in altri progetti.

Passare variabili alle procedure, alle funzioni o alle proprietà

Le variabili possono essere passate sia alle procedure, sia alle funzioni o alle proprietà. Le definizioni di Sub, Function o Property devono dichiarare se richiedono dei parametri:

  Sub SubName(Parameter1 As TYPENAME, Parameter2 As TYPENAME,...)
      ' il proprio codice va qui
  End Sub

La Sub (subroutine) viene chiamata con la sintassi seguente:

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

I parametri passati a una Sub devono corrispondere a quelli specificati nella relativa dichiarazione Sub.

Lo stesso processo si applica a una Function (funzione). Oltre a ciò, le funzioni restituiscono sempre un risultato. Questo risultato viene definito assegnando il valore da restituire al nome della funzione:

  Function FunctionName(Parameter1 As TYPENAME, Parameter2 As TYPENAME,...) As TYPENAME
      ' il proprio codice va qui
      FunctionName=Result
  End Function

La Funzione viene chiamata con la sintassi seguente:

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

Le proprietà combinano la sintassi delle procedure e delle funzioni. Una proprietà solitamente richiede al massimo un parametro.

  Private _IsApproved As TYPENAME
  Property Get IsApproved As TYPENAME
      ' il proprio codice va qui
      IsApproved = some_computation
  End Property
  Property Let IsApproved(value As TYPENAME)
      ' il proprio codice va qui
      _IsApproved = computed_value
  End Property

La Proprietà viene chiamata con la sintassi seguente:

  var = IsApproved
  IsApproved = some_value

È possibile usare anche il nome completo per richiamare una procedura, funzione o proprietà:
[Call] Library.Module.Macro() dove Call è facoltativo.
Ad esempio, per richiamare la macro per il testo automatico dalla libreria Gimmicks ricorrere al comando seguente:
Gimmicks.AutoText.Main()

Passare le variabili per valore o riferimento

I parametri possono essere passati a una procedura, a una funzione o a una proprietà sia come riferimento, sia come valore. A meno che non sia precisato diversamente, un parametro viene sempre passato come riferimento. Ciò significa che una Sub, una Function o una Property ottiene il parametro, lo può leggere e modificare il suo valore.

Se si vuole passare un parametro come valore, inserire la parola chiave ByVal prima del parametro nel momento in cui si richiama una Sub, una Function o una Property, per esempio:

  Function ReadOnlyParms(ByVal p2, ByVal p2)
      ' il proprio codice va qui
  End Function
  result = ReadOnlyParms(parm1, parm2)

In questo caso, il contenuto originale del parametro non verrà modificato dalla Funzione, poiché questa riceverà solo il valore e non il parametro vero e proprio.

Definire parametri opzionali

Le funzioni, le procedure e le proprietà possono essere definite con parametri opzionali, per esempio:

  Sub Rounding(number, Optional decimals, Optional format)
      ' il proprio codice va qui
  End Sub

Argomenti posizionali o di parole chiave

Quando si richiama una funzione o una subroutine, è possibile passare i relativi argomenti per posizione o per nome. Passare per posizione significa semplicemente elencare gli argomenti nell'ordine in cui i parametri sono definiti nella funzione o subroutine. Il passaggio per nome richiede il prefisso dell'argomento con il nome del parametro corrispondente seguito da due punti e da un segno di uguale (:=). Gli argomenti delle parole chiave possono essere visualizzati in qualsiasi ordine. Fare riferimento alla funzione Basic Replace() per tali esempi.

Quando è necessario passare meno parametri, utilizzare gli argomenti delle parole chiave. Il passaggio di valori per un numero inferiore di parametri per posizione richiede di fornire valori per tutti i parametri precedenti, facoltativi o meno. Ciò garantisce che i valori si trovino nelle posizioni corrette. Se si passano i parametri per nome, utilizzando argomenti di parole chiave, è possibile omettere tutti gli altri argomenti intermedi.

Ambito delle variabili

Una variabile definita all'interno di una Sub, una Function o una Property, rimane valida fino all'uscita dalla procedura. Questa viene definita come variabile "locale". In molti casi, si dovrà avere una variabile che sia valida in tutte le procedure e in tutti i moduli di tutte le librerie, oppure dopo l'uscita da una Sub, una Function o una Property.

Dichiarare variabili al di fuori di una Sub, una Function o una Property

Global VarName As TYPENAME

La variabile è valida per la durata della sessione di LibreOffice.

Public VarName As TYPENAME

La variabile è valida in tutti i moduli.

Private VarName As TYPENAME

La variabile è valida solo nel modulo attivo.

Dim VarName As TYPENAME

La variabile è valida solo nel modulo attivo.

Esempio per variabili private

Forza le variabili private a rimanere tali in altri moduli impostando CompatibilityMode(True).

  ' ***** Module1 *****
  Private myText As String
  Sub initMyText
      myText = "Ciao"
      Stampa "In modulo1 : ", mioTesto
  End Sub
   
  ' ***** Module2 *****
  'Option Explicit
  Sub demoBug
      CompatibilityMode( True )
      initMyText
      ' Ora restituisce una stringa vuota
      ' (o eleva errore per Option Explicit)
      Stampa "Ora in modulo2 : ", mioTesto
  End Sub

Salvare il contenuto di una variabile dopo l'uscita da una Sub, una Function o una Property

  Static VarName As TYPENAME

La variabile conserva il suo valore fino alla volta successiva in cui la Function, la Sub o la Property viene richiamata. La dichiarazione deve esistere all'interno di una Sub, una Function o una Property.

Specificare il tipo di valore di ritorno di una Function o di una Property

Come per le variabili, per definire il tipo di valore restituito della funzione o della proprietà inserire un carattere di dichiarazione del tipo dopo il nome della funzione, oppure il tipo indicato da As e dal tipo di dati corrispondente, alla fine dell'elenco dei parametri, ad esempio:

  Function WordCount(WordText As String) As Integer