Tutorial - creare un componente: il frame

Introduzione

Questo tutorial vuol essere di esempio per la realizzazione di un oggetto Frame, che andrà ad integrarsi come componente nell'ambiente di sviluppo del linguaggio di programmazione Gambas versione 3.

L'oggetto Frame, farà utilizzo di una classe genitore di tipo Container il quale verrà utilizzato per ereditare tutte le proprietà, metodi ed eventi che può un contenitore, di una Form che conterrà a sua volta una DrawingArea per il disegno dei bordi e del titolo, e di un Panel che sarà il reale contenitore di oggetti del Frame.

Creazione del Progetto

Una volta avviato Gambas, andiamo a selezionare le seguenti voci:

• Tipo Progetto: Applicazione Grafica
• Opzioni: Creazione di un componente

Dopo aver scelto la cartella che andrà a contenere il Progetto, inseriamo il titolo: gb.framebox.

A questo punto il nostro Esploratore di Progetti conterrà due classi di esempio che vengono generate di default, una Form di test e la cartella control dove risiederanno le icone dei vari oggetti del componente. Andiamo ad eliminare le due classi e le due icone, creando una nuova classe FrameBox, con opzione 'Esportato', e una Form a cui daremo il nome di FFrameBox.

Form FFrameBox

L'utilizzare una Form per la realizzazione di un oggetto grafico non è strettamente indispensabile in quanto si possono creare tutti gli oggetti grafici all'interno di una classe. Il solo scopo del suo utilizzo è per semplificare le operazioni di posizionamento e ridimensionamento degli oggetti che andranno a comporre il Frame.

Prima di tutto andiamo a posizionare la DrawingArea come primo strato del nostro oggetto, in quanto l'immagine che andrà a creare dovrà essere obbligatoriamente sul fondo, altrimenti non sarà possibile selezionare gli oggetti contenuti nel Frame. Dopodiché andremo ad inserire il Panel, senza preoccuparci della sua posizione.

Impostazioni degli oggetti

Le modifiche verranno apportate solamente alle proprietà sotto elencate, alle altre verranno lasciati i valori di default.

• FFrameBox

Name = FFrameBox
Arrangemet = Fill

Impostando questa proprietà, gli oggetti figli con proprietà Expand = TRUE si andranno a ridimensionare in automatico alle dimensioni del Form.

• DrawingArea

Name = DrawingArea1
Expand = TRUE

• Panel

Name = Panel1
Expan = TRUE

Stesura del Codice

Come prima cosa si dovranno decidere le varie proprietà che andranno a variare graficamente il Frame:

• Titolo
• Colore testo
• Tipo di carattere
• Bordi visibili
• Colore bordi

Dichiarazione delle Variabili Private

Private $Text As String
Private $TextColor As Integer
Private $Font As New Font
Private $Border As Boolean = True
Private $BorderColor As Integer

Essendo il codice 'di uso interno' andremo a creare solamente dei metodi per il settaggio di proprietà grafiche:

Public Sub SetText(Value As String)
  $Text = Value
  Me.DrawingArea1.Refresh()
End

Public Function GetText() As String
  Return $Text
End
 
Public Sub SetTexColor(Value As Integer)
  $TextColor = Value
  Me.DrawingArea1.Refresh()
End 

Public Function GetTextColor() As Integer
  Return $TextColor
End

Public Sub SetFont(Value As Font)
  $Font = Value
  Me.DrawingArea1.Refresh()
End

Public Function GetFont() As Font
  Return $Font
End

Public Sub SetBorder(Value As Boolean)
  $Border = Value
  Me.DrawingArea1.Refresh()
End

Public Function GetBorder() As Boolean
  Return $Border
End

Public Sub SetBorderColor(Value As Integer)
  $BorderColor = Value
  Me.DrawingArea1.Refresh()
End

Public Function GetBorderColor() As Integer
  Return $BorderColor
End

Da notare che per ogni variazione delle variabili, si richiama il metodo DrawingArea.Refresh() per poter applicare al volo le rispettive modifiche grafiche del frame.
A questo punto creiamo il disegno del Frame all'interno dell'evento Draw della DrawingArea:

Public Sub DrawingArea1_Draw()

  Paint.Begin(Me.DrawingArea1)
    Paint.Font = $Font
    Paint.Brush = Paint.Color($TextColor)
    Paint.Text($Text, 0, 0, Me.DrawingArea1.W, Paint.Font.TextHeight($Text) + 3, Align.Center)
    Paint.Fill()
    If $Border Then
      Paint.LineWidth = 0.5
      Paint.Brush = Paint.Color($BorderColor)
      Paint.MoveTo((Me.DrawingArea1.W - 5 - Paint.Font.TextWidth($Text)) / 2, Paint.Font.TextHeight($Text) / 2)
      Paint.LineTo(0, Paint.Font.TextHeight($Text) / 2)
      Paint.LineTo(0, Me.DrawingArea1.H)
      Paint.LineTo(Me.DrawingArea1.W, Me.DrawingArea1.H)
      Paint.LineTo(Me.DrawingArea1.w, Paint.Font.TextHeight($Text) / 2)
      Paint.LineTo(Me.DrawingArea1.W - ((Me.DrawingArea1.W - 5 - Paint.Font.TextWidth($Text)) / 2), Paint.Font.TextHeight($Text) / 2)
      Paint.Stroke()
    Endif
  Paint.End()

End

E per finire creiamo i metodi per variare la Proprietà Arrangement del Panel, in quanto sarà il vero contenitore del Frame:

Public Sub SetArrange(Value As Integer)
  Me.Panel1.Arrangement = Value
End

Public Function GetArrange() As Integer
  Return Me.Panel1.Arrangement
End

Classe FrameBox

Se nel Form appena creato abbiamo avuto una certa 'libertà' nella stesura del codice, adesso dobbiamo procedere con 'rigidità' per poter avere un componente pienamente funzionante nell'ide di Gambas.

Dichiarazione Proprietà, Costanti e Variabili Private

Per prima cosa andremo a dichiarare la classe Genitore:

Export

Inherits UserContainer

In questo modo abbiamo ereditato proprietà, metodi ed eventi dell'oggetto UserContainer
Poi andremo a dichiarare le costanti che serviranno all'ide di Gambas per l'integrazione del controllo:

Public Const _Properties As String = "*,Text,Foreground{Color}=&H000000&,BorderColor{Color}=&H000000H,Border=True"
Public Const _Group As String = "Gambas-it.org"
Public Const _Arrangement As Integer = 0
Public Const _Size As String = "36;36"

Dichiarazione delle Proprietà:

Property Text As String
Property Foreground As Integer
Property BorderColor As Integer
Property {Border} As Boolean
Property {Font} As Font
Property Arrangement As Integer

La Proprietà Arrangement è già compresa nelle Proprietà della classe genitore UserContainer. Dichiarandola nella classe figlia verrà automaticamente gestita da quest'ultima.

Private Obs As Observer

L'oggetto Observer intercetta gli eventi dell'oggetto a lui legato, prima che passino alla classe che ha istanziato il medesimo oggetto. Questo è utile per creare condizioni nell'oggetto, prima che scateni un evento. Nel nostro esempio non sarà indispensabile, ma siccome è un oggetto molto usato nei componenti, è bene sapere come funzioni.
Ed ora la FFrameBox che genererà la parte grafica del controllo:

Private F As FFrameBox