Visualizza wikitesto di Come creare un Componente scritto in linguaggio Gambas

== Introduzione ==

Un ''Componente'' non è altro che una classe (o una raccolta di classi) creata, con determinate caratteristiche, per poter essere integrata con l'ide di Gambas. Questa classe può essere un oggetto grafico (vedi la TableView di Gambas, che ha come classe genitore una GridView e permette l'inserimento di dati tramite una TextBox che si 'sposta' tra le celle) oppure una classe come Timer, che ha soltanto un'iconcina per essere visualizzata sul form, ma a 'lato pratico' è tutto codice.

La cosa importante che bisogna tener conto nella creazione di un Componente è il saper determinare se ne vale la pena crearlo. Se un Progetto presenta una classe creata ad hoc e non può essere riutilizzata in altri progetti, allora il creare un componente è solo una perdita di tempo. Al contrario, se il Progetto presenta classi 'riciclabili' allora il tempo speso a creare il componente verrà pienamente riguadagnato alla creazione di un nuovo Progetto che utilizza il medesimo componente.

== Creazione del Progetto Componente ==

Innanzi tutto per creare un Componente è necessario:  <SUP>&#91;[[#Note|nota 1]]&#93;</sup> <SUP>&#91;[[#Note|nota 2]]&#93;</sup>
 
* Avviare Gambas;
* Selezionare ''Nuovo Progetto'';
* Scegliere il tipo di Progetto;
* Scegliere il path del Progetto;
* Dare un nome al Progetto;
* Nel menu in alto cliccare su ''Progetto'', poi su ''Proprietà'';
* Nella finestra di dialogo che appare scegliere nella colonna di sinistra la voce ''Generale'', poi in ''Project type'' sciegliere ''Componente''.


È buona prassi chiamare il Progetto con la seguente sintassi:

  '''gb.'''''<nomeprogetto>''

In questo modo si identifica il Progetto come un componente.

Il Progetto deve avere queste caratteristiche:

'''Necessarie:'''
* Almeno una classe 'Esportabile'
* Elenco dei componenti utilizzati (se presenti)

'''Non necessarie:'''
* Costanti Pubbliche
* Icona del componente


==== Classe 'Esportabile' ====

All'atto della creazione di una nuova classe, bisogna spuntare la casella 'Esportato'.
In questo modo si rende 'visibile' all'esterno del progetto (vale anche per progetti 'non componenti') gli eventi, le proprietà pubbliche e i metodi pubblici della classe generata.
In caso ci si dimentichi di quest'ultima operazione, basta aggiungere una linea di codice scrivendo semplicemente Export all'inizio della classe.


==== Elenco dei componenti utilizzati ====

Se per creare il componente, si utilizzano degli altri componenti, bisogna aprire la gestione delle proprietà di Progetto, andare nella sezione 'Richiede', spuntare eventuali caratteristiche richieste dal componente e editare la lista dei componenti utilizzati.

In questo modo, si obbliga l'utente utilizzatore a selezionare eventuali componenti richiesti per integrare il componente nel Progetto.


==== Costanti Pubbliche ====

Le Costanti Pubbliche servono all'ide di Gambas per settare diverse caratteristiche del componente. 
Sono rese nascoste con il carattere _ antecedente il nome della Costante, per non essere riconosciute dall'ide di Gambas come costanti utilizzabili del componente.

===== Properties =====

''Dichiarazione''
 Public Const _Properties As String

Questa costante rende visibile le proprietà, separate da virgola, valorizzate all'interno della costante.
Le proprietà elencate, saranno visualizzate nella griglia delle proprietà poste sopra il ToolBox dei componenti nell'ide di Gambas. 

''Esempio:''
 Public Const _Properties As String = "*,Action,AutoResize,Text,Picture,Arrow=True,Border=True,Menu"

Il carattere '''*''' rende visibile tutte le proprietà ereditate dalla classe genitore (vedi [[INHERITS]]). Le restanti sono proprietà create all'interno della classe.

Per definire i valori delle proprietà, ci sono delle regole di sintassi da rispettare all'interno della stringa.

* Valore di Default
 <proprietà>=<Valore>
* Range di Valori
 <proprietà>{Range:<Valore min>;<Valore max>}
* Valori Costanti (es. Align.Center)
 <proprietà>{<classe>.<costante1>;<costante1>;<costante1>;...}
* Colori
 <proprietà>{Color}
* Liste
 <proprietà>{<NomeLista>[]}

Per particolari proprietà tipo Font, Picture, Image, l'ide di Gambas le riconosce automaticamente, visualizzando la corrispondente Form di settaggio della proprietà.

===== DefaultEvent =====

''Dichiarazione''
 Public Const _DefaultEvent As String

Setta l'evento di Default. 

Quando viene premuto il doppio click del mouse sopra l'oggetto nel form in costruzione, nella classe corrispondente viene creato il codice dell'evento di default.

===== Group =====

''Dichiarazione''
 Public Const _Group As String

Questa costante serve a posizionare il componente nella ToolBox di Gambas. 

''Esempio:''
 Public Const _Group As String = "Special"
Inserisce il componente nella Sezione Special accanto ai componenti Timer, Print, ..
Se viene specificata una sezione che non esiste di default, essa viene creata.

===== DefaultSize =====

''Dichiarazione''
 Public Const _DefaultSize As String

Setta le dimensioni di default all'atto dell'inserimento nel form di progettazione

''Esempio:''
 Public Const _DefaultSize As String = "36,36"

===== Similar =====

''Dichiarazione''  
 Public Const _Similar As String

===== Arrangement =====

''Dichiarazione''
 Public Const _Arrangement As Integer

Solo per Componenti di tipo 'Contenitore' setta il tipo di Arrangiamento dei sui oggetti figli in esso contenuti


==== Icona del componente ====

L'icona del componente determinerà la sua rappresentazione grafica nel ToolBox dell'ide di Gambas, nonché la rappresentazione dell'oggetto nel Form di progettazione, se non si ha settato la Costante DrawWith.

La Picture del componente deve avere una dimensione massima di '''32x32 pixel''', e deve avere il nome, scritto in '''minuscolo''', della classe che andrà a generare il componente, con estensione '''.png'''.

''Esempio:''
 Nome componente: gb.form
 Nome classe componente: ColorButton
 Nome della Picture: colorbutton.png
La Picture va inserita in un'apposita cartella di progetto. Quest'ultima va creata con il nome di '''control''' all'interno della cartella '''Progetto''', facilmente visualizzabile tramite l'esploratore di Progetto dell'ide di Gambas.


== Integrazione del Componente nell'IDE di Gambas ==

=== Installazione del Componente ===

L'integrazione del componente nell'IDE di Gambas è molto semplice se si ha Gambas installato tramite pacchetti di installazione. 

Nel nostro caso, allo stato attuale delle cose, Gambas3 non dispone ancora di una rilascio ufficiale, quindi verrà, per il momento, descritta solamente la procedura manuale.
==== Procedura Manuale ====

Per l'installazione del componente, si ha la necessità dei file elencati:

'''Necessari:'''
* Eseguibile del Progetto
* File .component
* File .list
* File .info

'''Non necessari:'''
* Icona del componente (se presente)

===== Descrizione dei File di Progetto =====

====== Eseguibile di Progetto ======

L'eseguibile del Progetto si ottiene andando a selezionare nel menù Progetto --> Crea --> Eseguibile...

Di default l'eseguibile viene generato all'interno della cartella principale di Progetto.

====== File .component ======

In questo file sono contenuti le principali proprietà del componente.

''Esempio''
 File .component del componente gb.form
 
 [Component]
 Key=gb.form
 Version=2.99.0
 Authors=Benoît Minisini
 Needs=Form

====== File .list ======

Il file contiene la lista delle classi Esportabili del componente.

''Esempio''
 File .list del componente gb.form
 
 Balloon
 ButtonBox
 ColorButton
 ColorChooser
 DateBox
 DateChooser
 DirChooser
 DirView
 Expander
 FileChooser
 FileView
 FontChooser
 InputBox
 ListContainer
 MenuButton
 Message
 SidePanel
 Stock
 TableView
 ToolPanel
 ValueBox
 Wizard
 _DateChooserColors

====== File .info ======

Il file .info è quello più complesso. In esso risiede il tracciato di tutte le proprietà, eventi, metodi delle classi Esportabili, in un formato sintetico, al quale l'ide di Gambas attinge per creare il 'Display property help' sul componente introdotto nel Progetto.

''Esempio''
 Parte del File .info del componente gb.form
 #Balloon
 
 C
 Control
 R
 Control
 
 Delay
 P
 i
 
 Font
 P
 Font
 
 Visible
 R
 b
 
 _call
 M
 
 (Message)s(Control)Control;[(Icon)Picture;(X)i(Y)i]
 Info
 M
 
 (Message)s(Control)Control;[(X)i(Y)i]
 Warning
 M
 
 (Message)s(Control)Control;[(X)i(Y)i]
 Error
 M 
 
 (Message)s(Control)Control;[(X)i(Y)i]
 Question
 M 
 
 (Message)s(Control)Control;[(X)i(Y)i]
 Delete
 M
 
 (Message)s(Control)Control;[(X)i(Y)i]
 Hide
 M 
 
 [(Control)Control;]

===== Copia dei File di Progetto =====

Per quanto riguarda i File di Progetto (escluso Icona e l'Eseguibile) devono essere copiati (anche nella medesima cartella di Progetto) e rinominati nel seguente modo:

''Esempio:''
 Nome Eseguibile gb.<nomecomponente>.gambas
 
 File .component = gb.<nomecomponente>.component
 File .info = gb.<nomecomponente>.info
 File .list = gb.<nomecomponente>.list

Questa operazione, assieme a quella di generare l'eseguibile, va rifatta se si apportano delle modifiche al componente.

I file generati, devono essere copiati nelle seguenti cartelle:

'''System.Path/lib/gambas3'''
* gb.<nomecomponente>.gambas
* gb.<nomecomponente>.component

'''System.Path/share/gambas3/info'''
* gb.<nomecomponente>.info
* gb.<nomecomponente>.list

Per l'Icona, se presente, va creata un'apposita cartella nella seguente posizione:

'''System.Path/share/gambas3/control/<nomecomponente>'''

In essa va poi copiata l'Icona al suo interno

Per ''System.Path'' si intende la cartella di sistema in cui è stato installato Gambas. Nel caso di distro Ubuntu con Gambas compilato da svn è:

'''/usr'''

=== Integrazione da Sorgenti ===

Dalla revisione 3352 si ha la possibilità di integrare i controlli creati senza doverli per forza installare.
I sorgenti dei controlli vanno semplicemente integrati nel progetto in opera e, una volta compilato, si avranno a disposizione i controlli già da subito nella ToolBox dei componenti.




----
=Note=
[1] Vedere al riguardo: https://gambaswiki.org/wiki/dev/gambas

[2] Le versioni ormai obsolete di Gambas riportano la precedente sequenza delle fasi, ossia:
* Avviare Gambas;
* Selezionare ''Nuovo Progetto'';
* Spuntare ''Creazione di un componente'';
* Scegliere il path del Progetto;
* Dare un nome al Progetto.