Uso di widget custom in Qt Creator

Il modo più semplice ed immediato per utilizzare una widget custom è quello di sfruttare il meccanismo di promozione di Qt Designer.

In pratica, ciò consiste nell'uso di una widget generica in qualità di segnaposto di quella propriamente desiderata nella finestra RAD del designer.

La widget generica può essere promossa ad un tipo specifico, di modo da rendere possibile l'inizializzazione della widget con il tipo corretto da parte di uic, durante la fase di compilazione dei sorgenti.

Ovviamente, nessuna proprietà specifica del tipo della widget custom sarà visibile o editabile nel pannello delle proprietà del designer, tuttavia sarà possibile disporre la widget nel layout desiderato e definirne le proprietà di base come nome, dimensioni, politiche di ridimensionamento eccetra.

La promozione richiede l'interazione con la finestra del designer. Per illustrare la procedura si farà riferimento alla widget custom introdotta nella lezione precedente, che sarà appunto l'oggetto della promozione.

Il primo passo consiste nell'aggiungere una widget generica laddove vorremmo che apparisse la widget custom nella modalità di editing RAD delle form di Qt Creator, e fare click su di essa con il tasto destro del mouse, come mostrato nella figura seguente:

Tra le varie opzioni disponibili nel menù contestuale, scegliendo Promote to si aprirà la finestra contenente l'elenco di widget promosse nel progetto corrente:

Di norma, l'elenco è vuoto fin tanto che non si effettua almeno una promozione, come in questo caso. Pertanto, il primo passo consiste nell'identificare il tipo della widget custom fornendo le informazioni seguenti:

• la classe base, tipicamente QWidget. Può essere una classe più specifica, ad esempio QLabel, QSpinBox eccetera, a seconda del caso;
• il nome della classe, in questo caso Led;
• il percorso dello header file corrispondente (led.h);
• la modalità di inclusione dello header file nei file generati da uic: quando l'opzione Global include è attiva la direttiva del preprocessore #include farà uso di parentesi angolari come in #include <led.h>, invece che di virgolette come in #include "led.h". Questa differenza può essere significativa a seconda di come è si struttura il progetto a livello di file system, e sarà discussa meglio nel seguito.

Una volta inseriti i dati richiesti è possibile cliccare sul pulsante Add per inserire la widget nell'elenco di classi promosse, come mostrato nella finestra seguente:

Poiché la widget Led risulta in elenco, è possibile selezionarla e cliccare sul pulsante Promote per completare la procedura.

Per effetto della promozione, nel pannello in alto a destra è possibile osservare che la classe dell'elemento segnaposto è adesso Led invece che QWidget, come mostrato nella figura seguente:

A questo punto si può procedere con le normali operazioni di editing della form, come ad esempio assegnazione di un layout, inserimento di altre widget, connessione di segnali e slot eccetra. Si può inoltre rinominare la widget custom per assegnarle un nome più pregnante, ad esempio led.

Poichè la widget custom è stata aggiunta da designer, la sua istanziazione e inizializzazione è demandata a uic. Pertanto, nel contesto della finestra che stiamo editando, è possibile accedere alla widget custom mediante il membro di classe ui.

Il frammento seguente riprende l'esempio illustrato nella lezione precedente, opportunamente modificato in seguito alla promozione:

#include "mainwindow.h"
#include "ui_mainwindow.h"
#include "led.h"
#include <QTimer>
 
MainWindow::MainWindow(QWidget *parent) :
    QMainWindow(parent),
    ui(new Ui::MainWindow)
{
    ui->setupUi(this);
     
    // la widget led, in quanto generata da uic, è accessibile
    // come membro di classe di ui.
    ui->led->setLightColor(Qt::green);
     
    QTimer *timer = new QTimer(this);
    connect(timer, &QTimer::timeout, this, [this] ()
    {
        // commuta lo stato del LED
        ui->led->setOn(!ui->led->isOn());
         
        // cambia il colore
        int hue = ui->led->getLightColor().hue();
        ui->led->setLightColor(QColor::fromHsv((hue + 15) % 360, 255, 255));
    });
     
    timer->start(500);
}
...

Altri usi della promozione

La promozione è uno strumento semplice che consente di usufruire della modalità di editing RAD anche con widget che non fanno parte del set predefinito del framework Qt. Il caso più frequente è quello di widget custom, ma esistono anche altre circostanze in cui essa può essere utile.

Ad esempio, è possibile ricorrere alla promozione anche nel caso di widget specifiche per la piattaforma target, oppure quando i sorgenti della widget non sono disponibili al momento della definizione dell'interfaccia.

Quando abilitare l'opzione Global include

Di norma i sorgenti di un'applicazione sono organizzati in più sottocartelle. Un progetto di Qt Creator, ad esempio, può articolarsi in più librerie e moduli.

La direttiva la preprocessore #include server per espandere i sorgenti in unità di traduzione complete, con l'inclusione di tutti gli header file necessari.

Non è infrequente, che gli header file risiedano in cartelle separate rispetto quelle dei file .cpp, o che si faccia riferimento a file header esterni, come quando la nostra applicazione fa uso di librerie di terze parti o di sistema.

In questi casi, invece di riportare esplicitamente l'intero percorso di un file header tra virgolette nella direttiva #include, è possibile usare le parentesi angolari per indicare al compilatore di ricercare i file header in un elenco di cartelle che viene fornito tra i vari parametri del comando di compilazione.

Ad esempio, il compilatore g++ predispone l'opzione -I seguita da un percorso completo per aggiungere una cartella a questo elenco.

Abilitare l'opzione Global include può essere utile proprio in questi casi, soprattutto se usata in sinergia con l'opzione INCLUDEPATH += "/mio/percorso" di qmake nel file di progetto (.pro).