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) consentono di mantenere una visione strutturata separando un programma in parti logiche. Queste parti si possono facilmente riutilizzare 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