Importare ed utilizzare librerie .gambas

In generale una Libreria è un insieme di istruzioni, comandi e risorse, esterno al codice del programma principale, che fornisce ulteriori ed addizionali funzionalità.

In Gambas è possibile utilizzare, oltre alle librerie condivise esterne .so, anche librerie .gambas, contenenti proprietà e funzioni ricavabili dalle risorse fornite da Gambas.

Potremmo definire le librerie .gambas come risorse intermedie tra un'applicazione ed un componente, in quanto esse possono possedere metodi, eventi e proprietà, non necessitano di essere installate nel sistema, ma possono essere utilizzate, come supporto ed integrative di risorse, da più programmi.

Più precisamente, una libreria Gambas è un progetto scritto una volta soltanto per essere integrato ed utilizzato in altri progetti, cioè in altri programmi. Esso fornisce Classi esportate e Moduli. In questo modo il codice della Libreria può essere anche riutilizzato.

Creare una libreria .gambas

La realizzazione di una libreria .gambas non richiede, solitamente, che siano mostrate finestre e Form, e pertanto, all'atto della creazione del tipo di progetto va scelta l'opzione " Applicazione a riga di comando ".

Il progetto avrà, come struttura iniziale ovviamente un Modulo principale Main.module, ma, affinché possa essere creata la libreria .gambas, bisognerà aggiungere almeno un modulo secondario. Si potranno, inoltre, utilizzare anche una o più Classi appositamente create all'interno della libreria.

V'è da sottolineare che, affinché le proprietà e le funzioni contenute in un Modulo o in una Classe di una libreria .gambas siano visibili (e dunque utilizzabili) in altri programmi Gambas, bisognerà avere l'accortezza di porre all'inizio del Modulo e della Classe la parola: Export, e di dichiarare dette funzioni e risorse come Pubbliche.

Si inseriranno successivamente nel Modulo e/o nella Classe le funzioni e le proprietà che si intende che la libreria metta a disposizione.

Quindi si cliccherà sulla voce di menu "Progetto ---> Proprietà".
All'apertura della finestra di dialogo nel ComboBox, posto al centro, alla voce "Tipo di Progetto" si dovrà impostare l'opzione "Libreria", e si premerà sul tasto "OK" per chiudere la finestra.

Infine, la libreria dovrà essere salvata cliccando su- menu "Progetto ---> Crea ---> Eseguibile". Nella finestra di dialogo apparirà automaticamente il nome (che potrà essere eventualmente cambiato a piacere) della Libreria già con l'estensione .gambas, ossia:

nome_libreria.gambas

Richiamare una libreria .gambas

Va precisato che questo tipo di librerie, costituite da codice Gambas, vanno poste nella medesima directory del programma che le utilizzerà, altrimenti le librerie non saranno trovate dal programma.

Va precisato, altresì, che, a differenza dell'utilizzo delle librerie condivise esterne .so, non è necessario dichiarare in alcun modo la libreria .gambas all'interno del codice della Classe principale del programma. La libreria .gambas andrà richiamata e impostata nel percorso del menu dell'IDE del progetto del programma principale "Progetto-->Proprietà", e poi nella finestra di dialogo, che sia apre, cliccando su "Librerie".

Invocare una funzione o altra risorsa posta in una libreria .gambas

Come già detto si potranno invocare funzioni ed altre risorse che siano poste in Moduli e Classi creati nella libreria .gambas .

Chiamata di funzioni poste all'interno di Moduli

Per invocare una funzione contenuta in un Modulo della libreria, si dovrà scrivere nel programma principale il nome del Modulo che la contiene e quindi il nome della funzione desiderata, in qualità di metodo di quel Modulo. Volendo si potrà invocare la funzione o altra risorsa nel programma principale anche attraverso la dichiarazione di una variabile del tipo del Modulo, presente nella libreria, contenente la funzione o la risorsa desiderata.

Chiamata di funzioni poste all'interno di Classi

Per invocare, invece, una funzione o un'altra risorsa contenuta in una Classe della libreria, sarà assolutamente necessario dichiarare nel programma principale una variabile del tipo della Classe, presente nella libreria, contenente la funzione o la risorsa desiderata, ed invocare quindi attraverso detta variabile la funzione o altra risorsa.

Chiamata da un Modulo di funzioni poste all'interno di Classi della medesima libreria

Parimenti, se deve essere invocata all'interno di un Modulo una funzione o altra risorsa posta in una Classe, entrambi presenti nella medesima libreria, la funzione ed ogni altra risorsa, presenti nella Classe, vanno invocate attraverso l'uso di una variabile dichiarata del tipo della Classe contenente la predetta funzione o risorsa.

Esempio pratico

Facciamo un esempio pratico, nel quale avremo una libreria, che chiameremo ad esempio "lib.gambas", ed un programma Gambas che ne richiama le funzioni presenti in una Classe ed in un Modulo di quella libreria.

Nella Classe, Classe1.class, della predetta libreria "lib.gambas" avremo il seguente codice:

Export


Public Function funzClasse(a As Integer) As Integer
 
 Dim b As Integer
 
   b = a * 7
   
   Return b
 
End

Nel Modulo, Module1.module, della libreria avremo il seguente codice analogo:

Export


Public Function funzModulo(a As Integer) As Integer
 
 Dim b As Integer
 
   b = a + 7
   
   Return b
 
End

Poi, nella Classe principale del programma avremo il seguente codice:

Public Sub Button1_Click()

 Dim cl As New Class1  ' Dichiariamo una variabile del tipo della Classe della libreria contenente la funzione da invocare
 Dim w, y As Integer

' Viene richiamata la funzione nella Classe della libreria ".gambas" :
   w = cl.funzClasse(5)
 
   Print w

 
' Viene richiamata la funzione nel Modulo della libreria ".gambas" :
   y = Module1.funzModulo(w)
 
   Print y
 
End

Ricordiamo che il programma e la predetta libreria .gambas devono risiedere nella medesima directory.

Sollevare un Evento

Nelle Librerie .gambas è possibile sollevare eventi. Come è noto, un evento può essere sollevato soltanto all'interno di una Classe, e non all'interno di un Modulo !

Si utilizzerà la parola Event per definire l'evento; ed esso sarà sollevato con il consueto comando Raise.

Facciamo un semplice esempio pratico.
Nella Libreria avremo in una Classe, che chiameremo: Class1.class, il seguente breve codice:

Export


Event eventoLibreria()


Public Sub prova(i as integer)

' Qui viene semplicemente sollevato l'evento:
  Raise eventoLibreria()

End

Nel programma principale avremo il seguente codice:

' Dichiariamo una variabile del tipo della classe "Class1", e viene assegnata al gruppo chiamato "classe",
' che useremo per intercettare gli eventi sollevati dalla Libreria .gambas:
Private cl As New Class1 As "classe"


Public Sub Button1_Click()

  cl.prova()

End


' Qui viene intercettato l'evento sollevato nella Liberia:
Public Sub classe_eventoLibreria()

 Print "E' stato intercettato l'evento sollevato dalla Liberia .Gambas !"

End

Intercettare dati ottenuti da file posti sotto osservazione con la parola Watch

Se nella libreria è previsto che un file qualsiasi sia aperto e sottoposto ad osservazione con la parola Watch, affinche vengano raccolti dati all'interno del collegato evento File_Read( ), il ritorno al programma principale dei dati così raccolti non sembra funzionare ponendo la parola Return. Sarà necessario, invece, sollevare un evento specifico mediante la parola Event, da richiamare nel programma principale, che ritorni esso in tal modo i dati appena raccolti.
Affinché possa essere sollevato un evento (intendiamo dire quello: File_Read() ) in una libreria, dovrà essere creata una Classe, non potendosi in generale sollevare eventi mediante un Modulo.

Poniamo come esempio una semplice libreria che apre un file in lettura e lo pone, appunto, sotto osservazione con la parola Watch. In tal modo, come si sa, quando v'è qualcosa da leggere nel file, sarà sollevato l'evento File_Read( ):

Private fl As File

' Dichiariamo l'evento specifico che sarà sollevato immediatamente dopo
' la sollevazione dell'evento "File_Read()".
' L'evento ritorna, in questo esempio, dei dati di tipo Integer:
Event eventoSpecifico(i As Integer)


Public Sub aperturaFile()

' Il file viene aperto in lettura e posto sotto "osservazione" in lettura:
' se c'è un dato da leggere nel file, viene sollevato direttamente l'evento "File_Read()":
  fl = Open "file_da_aprire" For Read Watch
 
End


Public Sub File_Read()
 
 Dim i As Integer
 
' Legge il nuovo contenuto del file posto sotto "osservazione":
   Read #fl, i
   
' Viene sollevato lo specifico evento, affinché i dati appena letti dal file
' possano essere trasferiti - in questo modo - al programma principale:
   Raise eventoSpecifico(i)
 
End

Nel programma principale l'evento specifico sarà richiamato nelle forme e modalità consuete.

Chiamare da una libreria .gambas una funzione contenuta in un'altra libreria .gambas

Può esservi il caso in cui un programma principale debba invocare una funzione contenuta in una libreria .gambas, la quale funzione - a sua volta - chiama una funzione contenuta in un'altra libreria .gambas .
Si avrà pertanto il programma principale e due librerie .gambas:

PROGRAMMA_PRINCIPALE---chiama-una-funzione-presente-in--->PRIMA_LIBRERIA.gambas--->che-chiama-una-funzione-presente-in--->SECONDA_LIBRERIA.gambas

Ecco come procedere.

1) E' opportuno cominciare dalla "coda"; pertanto si realizzerà, nelle modalità sopra descritte, innanzitutto la seconda libreria .gambas (ossia quella che sarà chiamata dalla prima libreria .gambas), e se ne creerà l'eseguibile (.gambas).

2) Si procederà quindi a creare, nelle modalità sopra descritte, la prima libreria .gambas (ossia quella direttamente chiamata dal programma principale), nella quale - prima di creare l'eseguibile - si dovrà caricare l'eseguibile della seconda libreria .gambas.

3) Nel programma principale sarà sufficiente caricare l'eseguibile della sola prima libreria .gambas (ossia di quella che poi invocherà la funzione presente nella seconda libreria .gambas).

Va ricordato che il programma principale e le due librerie .gambas devono coesistere nel medesimo percorso, nella medesima cartella.

Assegnare una libreria ad un progetto in modo dinamico.

Questo potrebbe rivelarsi utile per non costringere, chi riceve una nostra libreria, a doverla ricreare da zero.

Le librerie da noi create vengono salvate in "<user home>/.local/share/gambas3/lib/<vendor>/<nome libreria>", teniamone conto e passiamo alla pratica 1:

Andremo a creare una libreria che somma le valute in forma di stringa currency e poi la sfrutteremo in un progetto che somma dei subtotali e mostra il risultato in una textbox, il tutto sempre in forma di valuta.

Nella IDE di Gambas creiamo un nuovo progetto a riga di comando, lo intitoliamo LibSommaStringhe, diamo OK e aggiungiamo un nuovo modulo, per farlo, nel browser sulla sinistra diamo tasto destro del mouse su Sorgenti, aggiungiamo il modulo e lo nominiamo Mat e inseriamo questo codice in Mat.module:

 Export
 
 ' Ritorna la soma dei numeri 'stringa' come una stringa formattata currency 
 Public Function ReturnAddString(value As String[]) As String
 
   Dim sCurr As String
   Dim iCurr As Long
 
   For i As Integer = 0 To value.Max
     sCurr = ReturnStringInteger(value[i])
     iCurr += CLong(sCurr)
   Next
   Return Format((iCurr / 100), "$,0.00")
 
 End
 
 Private Function ReturnStringInteger(value As String) As String
 ' Ritorna una stringa in forma di numero intero 
   value = Trim(Replace(value, "€", ""))
   value = Replace(value, ".", "")
   value = Replace(value, " ", "")
   value = Replace(value, ",", "")
   Return value
 
 End

Si tratta di un'unica funzione pubblica del modulo che a sua volta si appoggia a una funzione privata per ottenere stringhe pulite di ogni carattere ad eccezione dei numeri per poi poterli cambiare in interi, sommarli e restituirli nuovamente in forma di valore monetario (currency).

Ora come già visto andiamo in Progetto > Proprietà scheda Generale > Tipo: scegliamo Libreria

In Venditore = softwarevendortest

In Versione = 010

In Titolo = Libreria Somma Stringhe

In Descrizione = Libreria che somma le stringhe in forma di valuta
Diamo OK

Dal menu Progetto > Crea > Eseguibile... creiamo un eseguibile.
Fatto

Ora procediamo con un nuovo progetto grafico che sfrutta la libreria: scegliamo gb.gui (Graphical application) o gb.gui.qt (QT application) a nostra preferenza e nominiamolo TestLibreria, diamo OK.
Nel browser del progetto sulla sinistra diamo tasto destro del mouse su Sorgenti e aggiungiamo un nuovo modulo che nominiamo MMain.
Ulteriore click destro su MMain per cambiarlo in Classe di avvio.
Prima di inserire il codice nel modulo, sempre nel browser ma questa volta agendo col tasto destro del mouse su Dati scegliamo il sotto menu Importa... e navighiamo fino al progetto libreria appena fatto per importarne l'eseguibile LibSommaStringhe.gambas.
Quindi in MMain.module aggiungiamo questo codice:

 Property Read sPath As String
 Private $sPath As String
 
 Public Sub Main()
 
   Dim sMessage As String = "Impossibile proseguire"
   Dim sLocalPath As String
 
   sLocalPath = User.Home &/ ".local/share/gambas3"
   If Not Exist(sLocalPath) Then Try Mkdir sLocalPath
   If Error Then
     Message.Error(sMessage)
     Return
   Endif
   sLocalPath &= "/lib"
   If Not Exist(sLocalPath) Then Try Mkdir sLocalPath
   If Error Then
     Message.Error(sMessage)
     Return
   Endif
   sLocalPath &= "/softwarevendortest"
   If Not Exist(sLocalPath) Then Try Mkdir sLocalPath
   If Error Then
     Message.Error(sMessage)
     Return
   Endif
   sLocalPath &= "/LibSommaStringhe:0.1.gambas"
   If Not Exist(sLocalPath) Then
     Try Copy "./LibSommaStringhe.gambas" To sLocalPath
     If Error Then
       Message.Error(sMessage)
       Return
     Endif
   Endif
 
   $sPath = sLocalPath
 
   FMain.Show
 
 End
   
 Private Function sPath_Read() As String
 
   Return $sPath
 
 End

Vediamo cosa fa il codice:
All'avvio del programma controlla se esiste già la cartella gambas3 altrimenti la crea, fa esattamente la stessa cosa con le cartelle lib e softwarevendortest (la cartella del venditore che potremmo nominare col nostro nome, l'importante è tenerne conto nel codice) controlla con Try che non avvengano errori altrimenti avvisa e esce dal progetto.
Se va tutto bene passa la stringa del percorso alla proprietà sPath e apre la finestra FMain.

La finestra FMain.form va disegnata con questi parametri:

Arrangement = Vertical

Height = 552

Margin = True

Spacing = True

Width = 512

Alla finestra va aggiunta in alto a sinistra una GridView con questi parametri:

Name = GridView1 (di default)

Expand = True

Height = 200

Width = 200

X = 8

Y = 8

Sotto la griview va disegnato un contenitore HBox:

Heigt = 32

Spacing = True

Width = 456

con al suo interno da sinistra a destra:

Uno Spring oppure in alternativa un pannello con la proprietà expand a True.

Un Button:

Name = btnTotal

Text = TOTALE

Width = 112

Una TextBox:

Alignment = Right

Width = 168

Ecco il codice per la finestra FMain.class:

 Private hCom As Component
 
 Public Sub Form_Open()
 
   Dim iRows As Integer = 20
   Dim fPrice, fValue As Float
   Dim fCasual As Float[] = [0.02, 0.04, 0.06, 0.2, 0.4, 0.6, 1, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 1.9]
 
   ' questo carica la libreria nel progetto 
   hCom = Component.Load(MMain.sPath)
   ' questo lo verifica scrivendo sulla console 
   Print hCom.Name;; hCom.Library;; hCom.Version
   ' Crea una lista di prezzi da poter sommare 
   ' cliccando sul pulsante total 
   With GridView1
     .Header = 3
     .Columns.Count = 1
     .Rows.Count = iRows
     .Columns[0].Text = "SUBTOTAL"
     .Columns[0].Alignment = Align.Right
     .Columns.Width = -1
   End With
   fPrice = CFloat(Time(Now)) * 1000
   For i As Integer = 0 To GridView1.Rows.Max
     fCasual.Shuffle()
     fValue = fPrice * fCasual.First
     GridView1[i, 0].Text = Format(fValue, "$,0.00")
   Next
 
 End
 
 
 Public Sub btnTotal_Click()
 
   Dim hMat As Class
   Dim sMetod As String
   Dim sSubTotal As New String[]
   
   ' Carica gli argomenti da passare al metodo della libreria. 
   For i As Integer = 0 To GridView1.Rows.Max
     sSubTotal.Push(GridView1[i, 0].Text)
   Next
   If hCom.Library Then hMat = Class.Load("Mat")
   sMetod = hMat.Symbols[0]
   ' Notare le parentesi che avvolgono il vettore degli argomenti che 
   ' va passato come un elemento del vettore variant dei simboli. 
   TextBox1.Text = Object.Call(hMat, sMetod, [sSubTotal])
 
 End

Vediamo cosa fa il codice.
All'apertura per prima cosa carica dinamicamente la libreria come fosse un componente e lo verifica stampando i risultati in console.
Sfruttando la data crea in modo random una serie di subtotali che scrive in forma di valuta (currency) nell'unica colonna della gridview.
Il codice del pulsante btnTotal carica dalla gridview in un vettore tutti i subtotali per poi passarli al metodo ReturnAddString ricevendone in cambio il totale formattato valuta.
Come già sottolineato nel commento del codice, vanno notate le parentesi quadre indispensabili per passare un vettore (subtotali) al vettore (symbol) del metodo in Object.Call.

Note

[1] potete anche fare riferimento a questa discussione del forum: [https://www.gambas-it.org/smf/index.php?topic=7868.msg48590#msg48590 ]