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: ^{[nota 1] [nota 2]}

• 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)

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.