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 create 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. Potete rinominare senza problemi questa Subroutine.

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

Le procedure (Subroutine), le funzioni (Function) e le proprietà (Property) vi aiutano a mantenere una visione strutturata dividendo un programma in parti logiche.

Uno dei vantaggi delle procedure, delle funzioni e delle proprietà è che, una volta sviluppato un codice di programma con componenti per un dato compito, potete usare lo stesso codice per 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 vostro 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 procedimento può essere applicato a unaFunzione per restituire il risultato di una funzione Tale risultato può essere definito direttamente prima di raggiungere la fine della funzione, assegnando il nome della funzione e un parametro al valore che dovrà essere restituito dalla funzione:

  Function FunctionName(Parameter1 As TYPENAME, Parameter2 As TYPENAME,...) As TYPENAME
      ' il vostro 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 vostro codice va qui
      IsApproved = some_computation
  End Property
  Property Let IsApproved(value As TYPENAME)
      ' il vostro codice va qui
      _IsApproved = computed_value
  End Property

La Proprietà viene chiamata con la sintassi seguente:

  var = IsApproved
  IsApproved = some_value

Potete 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 ricorrete 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 volete passare un parametro come valore, inserite la parola chiave ByVal prima del parametro nel momento in cui richiamate una Sub, una Function o una Property, per esempio:

  Function ReadOnlyParms(ByVal p2, ByVal p2)
      ' il vostro 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 vostro codice va qui
  End Sub

Argomenti posizionali o di parole chiave

Quando richiamate 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. Fate riferimento alla funzione Basic Replace() per tali esempi.

Quando è necessario passare meno parametri, utilizzate 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 passate i parametri per nome, utilizzando argomenti di parole chiave, potete 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, avrete la necessità di 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 : ", myText
  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 : ", myText
  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à inserite 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