Visualizza wikitesto di Creare, 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|Gambas]] è possibile utilizzare, oltre alle [[Extern:_richiamare_funzioni_esterne_a_Gambas|librerie condivise esterne .so]], <SPAN style="text-decoration:underline">anche</span> librerie '''.gambas''', scritte in linguaggio 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 Proprietà, Metodi ed Eventi, e non necessitano di essere installate nel sistema, ma possono essere utilizzate, come supporto e integrative di risorse, da più programmi Gambas.

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. <SUP>&#091;[[#Note|nota 1]]&#093;</sup>


==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 <SPAN style="text-decoration:underline">più</span> 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 ''<SPAN style="text-decoration:underline">Pubbliche</span>''.

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à'' ".
<BR>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==
Quando viene eseguito un progetto che dipende da una libreria ".gambas", l'eseguibile della libreria viene cercato nei percorsi secondo l'ordine indicato nella seguente pagina della wiki ufficiale:
 http://gambaswiki.org/wiki/doc/library?l=it#t2
Va precisato, altresì, che, a differenza dell'utilizzo delle [[Extern:_richiamare_funzioni_esterne_a_Gambas|librerie condivise esterne .so]], <SPAN style="text-decoration:underline">non</span> è 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 nella lista a sinistra su "''Librerie'' ". Quindi su "''Aggiungi'' " pertinente all'area di testo superiore delle due che appaiono. Infine si cliccherà sul nome della libreria riportata e sicliccherà sul tasto virtuale "OK".


==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:
 <FONT color=#B22222>'''Export'''</font>
 
 
 <FONT color=#B22222>'''Public'''</font> 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:
 <FONT color=#B22222>'''Export'''</font>
 
 
 <FONT color=#B22222>'''Public'''</font> 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()
 
 <FONT color=gray>' ''Dichiara una variabile del tipo della Classe della libreria contenente la funzione da invocare:''</font>
   Dim <FONT color=#B22222>cl As New Class1</font>
   Dim w, y As Integer
 
 <FONT color=gray>' ''Viene richiamata la funzione nella Classe della libreria ".gambas" :''</font>
   w = cl.funzClasse(5)
  
   Print w
  
 <FONT color=gray>' ''Viene richiamata la funzione nel Modulo della libreria ".gambas" :''</font>
   y = Module1.funzModulo(w)
  
   Print y
  
 End

Ricordiamo che il programma e la predetta libreria ''.gambas'' <SPAN style="text-decoration:underline">devono risiedere nella medesima directory</span>.


==Sollevare un Evento==
Nelle Librerie ''.gambas'' è possibile sollevare eventi. Come è noto, un evento può essere sollevato soltanto all'interno di una ''Classe'', e <U>non</u> all'interno di un ''Modulo'' !

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


Facciamo un semplice esempio pratico.
<BR>Nella Libreria avremo in una ''Classe'', che chiameremo: ''Class1.class'', il seguente breve codice:
 Export
 
 
 <FONT color=#B22222><B>Event</b></font> eventoLibreria()
 
 
 Public Sub prova(i as integer)
 
 <FONT color=gray>' ''Qui viene semplicemente sollevato l'evento:''</font>
   <FONT color=#B22222><B>Raise</b></font> eventoLibreria()
 
 End

Nel programma principale avremo il seguente codice:
 <FONT color=gray>' ''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:''</font>
 Private cl As New Class1 <FONT color=#B22222>As "classe"</font>
 
 
 Public Sub Button1_Click()
 
   cl.prova()
 
 End
 
 
 <FONT color=gray>' ''Qui viene intercettato l'evento sollevato nella Liberia:''</font>
 Public Sub <FONT color=#B22222>classe_eventoLibreria()</font>
 
   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.
<BR>Affinché possa essere sollevato un evento (intendiamo dire quello: "File_Read()" ) in una libreria, dovrà essere creata una ''Classe'', <SPAN style="text-decoration:underline">non</span> 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
 
 <FONT color=gray>' ''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:''</font>
 <FONT color=#B22222>'''Event''' eventoSpecifico(i As Integer)</font>
 
 
 Public Sub aperturaFile()
 
 <FONT color=gray>' ''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()":''</font>
   fl = Open "''file_da_aprire''" For Read <FONT color=#B22222>Watch</font>
  
 End
 
 
 Public Sub <FONT color=#B22222>File_Read()</font>
  
   Dim i As Integer
  
 <FONT color=gay>' ''Legge il nuovo contenuto del file posto sotto "osservazione":''</font>
   Read #fl, i
    
 <FONT color=gray>' ''Viene sollevato lo specifico evento, affinché i dati appena letti dal file possano essere trasferiti - in questo modo - al programma principale:''</font>
   <FONT color=#B22222>Raise eventoSpecifico(i)</font>
  
 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 .
<BR>Si avrà pertanto il programma principale e due librerie .gambas:
 <FONT Size=4><B>PROGRAMMA_PRINCIPALE</b></font>---chiama-una-funzione-presente-in---><FONT Color=blue>PRIMA_LIBRERIA.gambas</font>--->che-chiama-una-funzione-presente-in---><FONT Color=#B22222>SECONDA_LIBRERIA.gambas</font>
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: <SUP>&#091;[[#Note|nota 2]]&#093;</sup>

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 così: nel browser sulla sinistra diamo tasto destro del mouse su ''Sorgenti'', aggiungiamo il modulo, lo nominiamo '''Mat''' e inseriamo questo codice in ''Mat.module'':
  Export
  
  <FONT Color=gray>' ''Ritorna la somma dei numeri 'stringa' come una stringa formattata currency'' </font>
  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
  <FONT Color=gray>' ''Ritorna una stringa in forma di numero intero'' </font>
   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'' e scegliamo ''Libreria'' <br>
:In Venditore = ''softwarevendortest''
:In Versione = 0-1-0 
:In Titolo = ''Libreria Somma Stringhe'' 
:In Descrizione = ''Libreria che somma le stringhe in forma di valuta''<br>Diamo '''OK'''

Dal menu ''Progetto > Crea > Eseguibile...'' creiamo un eseguibile.
<br>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'''.
<br>Nel browser del progetto sulla sinistra diamo tasto destro del mouse su ''Sorgenti'' e aggiungiamo un nuovo modulo che nominiamo ''MMain''.
<br>Ulteriore click destro su MMain per cambiarlo in ''Classe di avvio''.
<br>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''.
<br>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:
<br>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.
<br>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 gridview 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]
  
 <FONT Color=gray>' ''questo carica la libreria nel progetto'' </font>
   hCom = Component.Load(MMain.sPath)
 <FONT Color=gray>' ''questo lo verifica scrivendo sulla console'' </font>
   Print hCom.Name;; hCom.Library;; hCom.Version
 <FONT Color=gray>' ''Crea una lista di prezzi da poter sommare, cliccando sul pulsante btnTotal'' </font>
   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[]
   
  <FONT Color=gray>' ''Carica gli argomenti da passare al metodo della libreria.'' </font>
   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]
 <FONT Color=gray>' ''Notare le parentesi che avvolgono il vettore degli argomenti che va passato come un elemento del vettore variant dei simboli.'' </font>
   TextBox1.Text = Object.Call(hMat, sMetod, [sSubTotal])
  
 End
Vediamo cosa fa il codice.
<br>All'apertura per prima cosa carica dinamicamente la libreria come fosse un componente e lo verifica stampando i risultati in console.
<br>Sfruttando la data crea in modo random una serie di subtotali che scrive in forma di valuta (''currency'') nell'unica colonna della ''gridview''.
<br>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.
<br>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]  Gambas fa parte dei linguaggi ''interpretati'', e quindi non ha il concetto di libreria dinamica.
<BR>Il concetto di ''libreria'' è solo inteso come codice riutilizzabile.

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



=Riferimenti=
* http://gambaswiki.org/wiki/doc/library?l=it