[WELCOME]

<h3>Benvenuto in <b>Gambas</b>!</h3>

<p><b>Gambas</b> è un ambiente grafico di sviluppo basato su un interprete avanzato 
<i>Basic</i>.</p>

<p>L'obiettivo di <b>Gambas</b> è quello di permettere di creare programmi potenti 
in maniera facile e veloce. Ma la responsabilità di creare programmi puliti è tutta <i>vostra</i>...</p>

<p>Spero vi piaccia!</p>

<p align=right>Beno&icirc;t Minisini<br>
<u>benoit.minisini@gambas-basic.org</u><br><br><br></p>


[STARTUP]

<h3>Classe di avvio</h3>

<p>Ogni progetto deve avere una <i>classe di avvio</i>.
 Questa classe di avvio deve definire un metodo pubblico <i> (public)</i> e statico <i>(static)</i>
 denominato <i>Main</i> senza argomenti, che si comporterà come il metodo di inizio del tuo programma</p>

<p>Puoi definire la classe di avvio cliccando su di essa con il tasto destro del mouse e selezionando <i>Classe di avvio</i>
nel menù a cascata</p>

<p>Non è necessario definire un metodo <i>Main</i> in un Form di avvio perché ne esiste già uno predefinito.</p>

<p>Questo metodo predefinito inizializza il form e lo mostra, come in <i>Visual Basic&trade;</i>.</p>


[OPEN]

<h3>Open</h3>

<p>L'Istruzione <b>OPEN</b> di <b>Gambas</b> non si comporta nella stessa maniera
 che in <i>Visual Basic</i>.
 Non ritorna il file come un <i>Integer</i>, ma come un ogetto <i>File</i>.</p>

<p>In pratica, invece di digitare:</p>

<pre>DIM handle AS Integer
...
OPEN "ilmiofile" FOR READ AS #handle</pre>

<p>Devi digitare :</p>

<pre>DIM handle AS File
...
handle = OPEN "ilmiofile" FOR READ</pre>


[CATDIR]

<h3>Concatenazione dei percorsi</h3>

<p>Lo sapevi che puoi concatenare nomi di directory e nomi di file
con l'operatore <b><tt>&/</tt></b>?
Questo operatore aggiunge se necessario la <i>slash</i> ("/") in maniera tale che 
l'indirizzo risultante sia perfetto.</p>

<p>Per esempio :</p>

<pre>PRINT "/home/gambas" &/ ".bashrc"
/home/gambas/.bashrc

PRINT "/home/gambas/" &/ "/tmp" &/ "foo.bar"
/home/gambas/tmp/foo.bar
</pre>

<p>Non è stupendo ?</p>

[EXEC]

<h3>Eseguibile</h3>

<p>Puoi realizzare un file eseguibile di tutto il tuo progetto.
 Seleziona <i>Crea eseguibile</i> nel menu  <i>Progetto</i>.</p>

<p>Quando <b>Gambas</b> crea un file eseguibile, colloca il risultato direttamente
nella directory del tuo progetto e il nome del file eseguibile sarà quello del 
tuo progetto</p>


[PATH]

<h3>Percorsi relativi</h3>

<p>
I percorsi relativi hanno un significato speciale in <b>Gambas</b>.
Sono sempre riferiti a file dentro il tuo progetto.
<p>
Non c'è il concetto di <i>directory corrente</i>, e nessuna parola chiave come
<tt>CHDIR</tt> per cambiarla.
<p>
<b>Attenzione:</b> devi usare i percorsi relativi solo per accedere ai file di 
progetto, perché i percorsi assoluti non funzioneranno quando crei l'eseguibile.


[GLOBAL]

<h3>Variabili globali</h3>

Non ci sono <u>variabili globali</u> in <b><i>Gambas</i></b>!
<p>
Come sostituto, dichiarale nel modulo principale come <tt>PUBLIC</tt>.
<p>
Se non hai un modulo principale nel tuo progetto, ma un form principale, 
allora dichiarale come <tt>STATIC PUBLIC</tt>.
<p>
Per accedere a queste variabili, devi usare il nome del modulo principale
o form: <tt>MyMainModule.MyGlobalVariable</tt> o
<tt>MyMainForm.MyGlobalVariable</tt>.

[EMPTY]

<h3>Stringhe vuote</h3>

<p>Per sapere se una stringa è vuota non è necessario usare la funzione <b>Len()</b> .
 Puoi direttamente testare la stringa, visto che una stringa vuota è <b>FALSE</b> e una non vuota è <b>TRUE</b>.</p>

<p>Per esempio, invece di :</p>

<pre>IF Len(Lamiastringa) > 0 THEN ...
IF Len(Lamiastringa) = 0 THEN ...</pre>

<p>Puoi fare :</p>

<pre>IF Lamiastringa THEN ...
IF NOT Lamiastringa THEN ...</pre>


[TRANSLATE]

<h3>Traduzione</h3>

<p>Le applicazioni Gambas sono completamente traducibili, a condizione
che tu dica quali stringhe devono essere tradotte e quali no.</p>
<p>Per contrassegnare le stringhe come traducibili, racchiudile tra parentesi tonde:<p>

<pre>Print ("Traducimi")
Print "Non tradurmi!"</pre>


[SUBST]

<h3>Subst$</h3>

<p>La funzione <b><tt>Subst$()</tt></b> è molto utile per internazionalizzare la tua applicazione.</p>

<p>Ci vogliono almeno due argomenti. Il primo è la maschera di testo su cui si applica la sostituzione.
Gli altri sono gli argomenti di sostituzione, numerati a partire da uno.</p>

<p>Ogni modello <tt>&X</tt> nella stringa di sostituzione verrà sostituito dall'argomento di sostituzione X.
Per esempio:</p>

<pre>Print Subst(("Sostituzione di &1, &2 e &3"),
  "primo", "secondo", "terzo")

&rarr; Sostituzione di primo, secondo e terzo</pre>

[EVENT]

<h3>Gestori di eventi</h3>

<p>Tutti i controlli e tutti gli oggetti che possono avere eventi,
 hanno un <i>Osservatore di eventi</i> e un <i>nome di gruppo</i> del evento.</p>

<p>L'osservatore di eventi coglie tutti gli eventi prodotti dall'oggetto,
 e il nome del gruppo del evento è il prefisso del procedimento incaricato di gestire l'evento.</p>

<p>Di default, questo osservatore di eventi è l'oggetto dove si è creato il controllo,
 e il nome di gruppo è il nome del controllo.</p>

<p>In questo modo, un form riceve tutti gli eventi prodotti dai controlli che tu ci hai creato dentro.</p>

<pre>' Gambas form

DIM hButton AS Button

PUBLIC SUB _new()
&nbsp;&nbsp;...
&nbsp;&nbsp;hButton = NEW Button(ME) AS "Ilmiopulsante"
&nbsp;&nbsp;...
END

PUBLIC SUB Ilmiopulsante_Click()
&nbsp;&nbsp;...
END
</pre>


[GROUP]

<h3>Gruppi di controlli</h3>

<p>Tutti i controlli hanno una proprietà <i>(Group)</i>.
 Quando questa proprietà è utilizzata, il prefisso del gestore di eventi è il nome del
 gruppo e non il nome  del controllo.</p>
<p>Supponiamo di avere un <i>Button</i> chiamato <b>btnAzione</b> con il gestore di eventi <i>Click</i>
seguente :</p>

<pre>PUBLIC SUB btnAzione_Click()</pre>

<p>Se definisci la proprietà <i>(Group)</i> di <b>btnAzione</b> come <i>IlMioGruppo</i>,
 Allora il gestore di eventi che riceverà gli eventi del pulsante sarà il seguente:</p>

<pre>PUBLIC SUB IlMioGruppo_Click()</pre>

<p>Questa proprietà permette di gestire vari eventi con una semplice funzione.
 E i controlli dello stesso gruppo non devono per forza essere dello stesso tipo !!!</p>

<p><b>Nota :</b> I veterani del vecchio <i>Visual Basic</i> riconosceranno il concetto di <i>control array</i>,
 soltanto che qui viene implementato in un modo più potente. :-)</p>


[FORM]

<h3>Form</h3>

<p>Un form è l'osservatore di eventi di se stesso, in questo modo puoi gestire direttamente i suoi eventi (<i>Resize</i>, <i>Activate</i>, ...)
dentro il codice della sua stessa classe.</p>

<p>In questo modo, i nuovi arrivati da <i>Visual Basic</i> non si sentiranno persi :-).</p>


[EMBED]

<h3>Incorporare i Form</h3>

<p>Con <b><i>Gambas</i></b> puoi fare in modo che qualsiasi form venga
racchiuso in un altro form!</p>

<p>Per fare una cosa così utile devi soltanto inizializzare il form passando 
un contenitore padre come ultimo argomento nel costruttore.</p>

<p>Per esempio :</p>
<p><tt>DIM hForm AS MyDialog<br>
DIM hSuperControl AS MyForm<br><br>
' Crea un dialogo<br>
hForm = NEW MyDialog<br>
' Inserisce un form in questo dialogo<br>
' Nota che questo form riceve due parametri prima del contenitore<br>
hSuperControl = NEW MyForm(Param1, Param2, MyDialog)<br>
' Muove e ridimensiona il form<br>
hSuperControl.Move(8, 8, 128, 64)</tt><br>

<p>Ricorda che: un form racchiuso in un altro continua ad essere un form
 e quindi osservatore di eventi di se stesso.</p>


[TAG]

<h3>Proprietà Tag</h3>

<p>Tutti i controlli hanno una proprietà chiamata <i>Tag</i>
 Questa proprietà è pensata per essere usata dai programmatori e può contenere qualsiasi dato 
<b>VARIANT</b> che credi utile.</p>

<p>Questo è molto utile quando vuoi differenziare controlli dello stesso gruppo nello stesso gestore di eventi.</p>


[LAST]

<h3>Last</h3>

<p>La parola chiave <b>LAST</b> ritorna l'ultimo controllo che ha ricevuto un evento.
 E' molto utile quando vuoi scrivere un gestore di eventi 
che sia indipendente dal nome del controllo.</p>

<p>Supponiamo di voler scrivere un programma calcolatrice.
 Hai definito dieci pulsanti, uno per ogni numero e tutti con lo stesso <i>group</i> "Digit".
 Il valore del <i>Tag</i> di ogni controllo sarà il numero visualizzato da ogni pulsante.
 Il tuo gestore di eventi sarà più o meno così :</p>

<p><tt>PUBLIC SUB Digit_Click()<br><br>
&nbsp;&nbsp;Display = Display & LAST.Tag<br>
&nbsp;&nbsp;RefreshDisplay<br><br>
END</tt></p>


[LEFT]

<h3>Left$ / Mid$ / Right$</h3>

<p>Le famose routine <b>Left$</b>, <b>Right$</b>, <b>Mid$</b> di <i>BASIC</i>
 hanno un comportamento molto utile in <b><i>Gambas</i></b>.</p>

<p>Il secondo parametro di <b>Left$</b> e <b>Right$</b> è facoltativo, e per default è pari a uno.</p>

<p><tt>Left$("Gambas")</tt> ritorna <tt>"G"</tt><br>
<tt>Right$("Gambas")</tt> ritorna <tt>"s"</tt></p>

<p>Il secondo parametro può essere negativo e in questo caso rappresenta il numero di caratteri da non ritornare.</p>

<p><tt>Left$("Gambas", -2)</tt> ritorna <tt>"Gamb"</tt><br>
<tt>Right$("Gambas", -2)</tt> ritorna <tt>"mbas"</tt></p>

<p>Allo stesso modo, il terzo parametro di <b>Mid$</b> può essere negativo,
 e quindi rappresentare il numero di caratteri dalla fine della stringa da non ritornare.</p>

<p><tt>Mid$("Gambas", 2, -2)</tt> ritorna <tt>"amb"</tt>


[OBSERVER]

<h3>Observer</h3>

<p>La classe <b>Observer</b> ti consente di intercettare tutti gli eventi generati da un
oggetto prima che vengano effettivamente inviati.</p>

<pre>MyTextBox = New TextBox(Me) As "MyTextBox"
MyObserver = New Observer(MyTextBox) As "MyObserver"
...
Public Sub MyObserver_KeyPress()
  Debug "Got it first"
End

Public Sub MyTextBox_KeyPress()
  Debug "Got it next"
End</pre>

L'osservatore può annullare l'evento con <tt>Stop Event</tt> per prevenire l'oggetto dal 
sollevarlo effettivamente.


[STRING]

<h3>UTF-8 Strings</h3>

<p><b>Gambas</b> utilizza il set di caratteri <b>UTF-8</b> per rappresentare le stringhe in memoria.

<p>Ma tutte le funzioni di stringa standard riguardano solo <b>ASCII</b>: 
<tt>Left</tt>, <tt>Mid</tt>, <tt>Right</tt>, <tt>UCase</tt>...

<p>Se si desidera gestire le stringhe UTF-8, è necessario utilizzare i metodi della classe statica
<b>String</b>, che hanno lo stesso nome delle loro controparti standard.

<pre>Print Len("bébé");; Left$("bébé", 3)
&rarr; 6 bé

Print String.Len("bébé");; String.Left("bébé", 3)
&rarr; 4 béb</pre>


[ASSIGNMENT]

<h3>Assegnazioni</h3>

<p><b>Gambas</b> implementa le scorciatoie di assegnazione a cui i programmatori C / C ++ sono abituati.

<pre>MyVariable += 2
MyVariable *= 4
MyVariable &= "Great"</pre>
è un equivalente di
<pre>MyVariable = MyVariable + 2
MyVariable = MyVariable * 4
MyVariable = MyVariable & "Great"</pre>

<p>E così via...


[DEBUG]

<h3>Debug</h3>

<p>È possibile utilizzare l'istruzione <b><tt>Debug</tt></b> per stampare messaggi di debug sulla
console (ovvero l'output di errore standard). Si comporta esattamente come l'istruzione <tt>Print</tt>.

<p>Questi messaggi hanno come prefisso il nome della classe, il nome del metodo e il numero di
riga dell'istruzione <tt>Debug</tt>. Se non si desidera il prefisso, è possibile utilizzare 
l'istruzione <b><tt>Error</tt></b> anziché <tt>Debug</tt>.

<p>I messaggi di debug vengono automaticamente rimossi durante la creazione di
un eseguibile senza eseguire il debug delle informazioni.


[TRY]

<h3>Gestione degli errori (1)</h3>

<p>La gestione degli errori in <b>Gambas</b> viene eseguita con le seguenti istruzioni: 
<b><tt>Try</tt></b>, <b><tt>Error</tt></b>, <tt>Catch</tt>, and <tt>Finally</tt>.

<p><tt>Try</tt> prova a eseguire una dichiarazione senza generare un errore. La parola chiave 
<tt>Error</tt> viene utilizzata subito dopo per sapere se l'istruzione è stata eseguita correttamente.

<pre>Try MyFile = Open "/etc/password" For Write
If Error Then Print "Non posso fare quello che voglio!"</pre>


[CATCH]

<h3>Gestione degli errori (2)</h3>

<p>La gestione degli errori in <b>Gambas</b> viene eseguita con le seguenti istruzioni: 
<tt>Try</tt>, <tt>Error</tt>, <b><tt>Catch</tt></b>, and <tt>Finally</tt>.

<p><tt>Catch</tt> indica l'inizio della parte di gestione degli errori di una funzione o procedura.
È messo alla fine del codice della funzione.

<p>La parte catch viene eseguita quando viene generato un errore tra l'inizio dell'esecuzione della funzione e la sua fine.

<p>Se viene sollevato un errore durante l'esecuzione della parte catch, l'errore viene propagato normalmente. 

<pre>Sub ProcessFile(FileName As String)
  ...
  Open FileName For Read As #hFile
  ...
  Close #hFile
  
Catch ' Eseguito solo se c'è un errore

  Print "Impossibile elaborare il file "; FileName

End</pre>


[FINALLY]

<h3>Gestione degli errori (3)</h3>

<p>La gestione degli errori in <b>Gambas</b> viene eseguita con le seguenti istruzioni: 
<tt>Try</tt>, <tt>Error</tt>, <tt>Catch</tt>, and <b><tt>Finally</tt></b>.

<p><tt>Finally</tt> introduce il codice eseguito alla fine della funzione, anche se viene sollevato un errore durante l'esecuzione. 

<p>La parte finally non è obbligatoria. Se c'è una parte catch nella funzione, la parte finally deve precederla. 
 
<p>Se viene generato un errore durante l'esecuzione della parte finally, l'errore viene propagato normalmente.

<pre>Sub ProcessFile(FileName As String)
  ...
  Open FileName For Read As #hFile
  ...
Finally ' Viene sempre eseguito, anche se viene sollevato un errore

  Close #hFile
  
Catch ' Eseguito solo se c'è un errore
  
  Print "Impossibile stampare il file "; FileName
  
End</pre>


[OPTIONAL]

<h3>Optional</h3>

<p>Le funzioni e le procedure in <b>Gambas</b> possono avere argomenti opzionali.</p>

<p>Gli argomenti opzionali vengono semplicemente fatti mettendo la parola chiave <b><tt>Optional</tt></b> subito prima del nome dell'argomento.</p>

<p>Gli argomenti opzionali possono avere anche un valore predefinito esplicito.</p>

<pre>Private Sub MyFunction(Param AS String, Optional Optim AS String = "Default")
  ...
  Print "Necessario: "; param; ", Opzionale: "; optim
  ...
End</pre>


[ARRAY]

<h3>For Each</h3>

<p>In <b>Gambas</b> puoi facilmente scorrere un array, una raccolta o molte altre classi enumerabili con l'istruzione <b><tt>For Each</tt></b>.</p>

<p>Per esempio:</p>

<pre>Dim Xml As New XmlDocument
Dim Node As XmlNode
Dim I As Integer

' Apre un file XML
Xml.Open("pokus.xml")
' I children sono indicizzati tramite [i], poiché si tratta di un array
For I = 0 To Xml.Root.Children.Count - 1
  ' Gli attributi vengono ciclati tramite For Each, poiché si tratta di una collection
  For Each Node In Xml.Root.Children[i].Attributes
    Print Node.Name;; Node.Value
  Next
Next</pre>


[ICON]

<h3>Icone di default</h3>

<p>Puoi utilizzare le icone incorporate per una migliore GUI della tua applicazione, le icone sono disponibili in diverse dimensioni predefinite 
(<tt>"small"</tt>, <tt>"medium"</tt>, <tt>"large"</tt>,...) o in dimensioni assolute (da 16x16 a 256x256).</p>

<p>Per esempio:

<pre>Image1.Picture = Picture["icon:/32/warning"]
Image2.Picture = Picture["icon:/small/error"]
</pre>

<p><b>Attenzione:</b> è richiesto il componente <tt>gb.form</tt>.


[SETTINGS]

<h3>Settings</h3>

<p>Se hai bisogno di memorizzare la configurazione del tuo programma (come la geometria dei tuoi form), allora sei un ragazzo fortunato. In <b>Gambas</b> è molto semplice ed elegante. :-)

<p>Per salvare la posizione di un form:
<pre>Settings.Write(TheForm)</pre>

<p>Per richiamarlo:
<pre>Settings.Read(TheForm)</pre>

Per salvare qualsiasi impostazione:
<pre>Settings["Slot/Key"] = Value</pre>

E per rileggerne le impostazioni:
<pre>Value = Settings["Slot/Key", DefaultValue]</pre>

Queste impostazioni sono memorizzate nel file <tt>~/.config/gambas3/&lt;MyApplication&gt;.conf</tt>,
dove <tt>&lt;MyApplication&gt;</tt> è il nome del tuo progetto.

<p><b>Attenzione:</b> è richiesto il componente <tt>gb.settings</tt>.


[EDITOR]

<p>Ecco alcuni suggerimenti per l'editor...</p>

<h3>Due tipi di commenti</h3>

<pre>' Commento normale</pre>
<b><pre>'' Commento in grassetto</pre></b>

<p>I commenti in grassetto sono usati per documentare il tuo codice.</p>

<h3>Come utilizzare i frammenti di codice</h3>

<p>Digita <tt>main</tt> quindi il tasto <b>TAB</b>. Una funzione statica e pubblica di avvio <tt>Main</tt> viene automaticamente inserita nel codice.

<p>Digita <tt>ds</tt> quindi il tasto <b>TAB</b>. Una dichiarazione locale di variabile stringa viene inserita automaticamente ed è possibile digitare immediatamente il nome della variabile.

<p>I frammenti di codice sono completamente configurabili dalla finestra di dialogo Preferenze del menu Strumenti dell'IDE.


[END]

<h3>Questo è tutto gente!</h3>

<p>Hai letto tutti i suggerimenti del giorno. Spero che ora tu sia un esperto di <b>Gambas</b> ! :-)</p>

<p>Se vuoi contribuire, invia i nuovi consigli al seguente indirizzo :</p>
<p><u>user@lists.gambas-basic.org</u></p>

<p>Grazie in anticipo !</p> 

