Getting Started with Qt/it

h1. Iniziare a programmare con Qt

Benvenuto nel mondo di Qt, lo strumento multipiattaforma per lo sviluppo di GUI. In questa guida, insegneremo i fondamenti delle nozioni di Qt creando una sempplice applicazione Notepad. Dopo aver letto la guida, si dovrebbe essere in grado di cercare all'interno delle nostre panoramiche e nella documentazione delle API per trovare le informazioni di cui si necessita per sviluppare l'applicazione a cui si sta lavorando.

Hello Notepad

In questo primo esempio creeremo e visualizzeremo un editor di testo in una finestra sul desktop. Questo rappresenta il più semplice programma Qt dotato di interfaccia utente.

p=. gs1.png

Il codice è il seguente:

 #include <QApplication>
#include <QTextEdit>

int main(int argv, char **args)
{
 QApplication app(argv, args);

QTextEdit textEdit;
 textEdit.show();

return app.exec();
}

Analizziamo ora il codice riga per riga. Nelle prime due righe includiamo i file header per "QApplication":http://doc.qt.nokia.com/4.7/qapplication.html e "QTextEdit":http://doc.qt.nokia.com/4.7/qtextedit.html, le due classi che ci servono per questo esempio. Tutte le classi Qt hanno un file header avente il loro stesso nome.

La riga 6 crea un oggetto "QApplication":http://doc.qt.nokia.com/4.7/qapplication.html. Questo oggetto gestisce le risorse all'interno di tutta l'applicazione ed è necessario per eseguire ogni programma Qt che possiede una GUI. "QApplication":http://doc.qt.nokia.com/4.7/qapplication.html richiede argv e args poiché Qt accetta alcuni argomenti a linea di comando.

La riga 8 crea un oggetto "QTextEdit":http://doc.qt.nokia.com/4.7/qtextedit.html. Un editor di testo è un elemento grafico nella GUI. In Qt questi elementi vengono definiti widgets. Esempi di altri widgets sono barre di scorrimento, labels e radio buttons. Un widget può inoltre contenere altri widgets, ne sono un esempio la finestra di dialogo e la main window dell'applicazione.

La riga 9 mostra nella sua finestra sullo schermo l'editor di testo. I widgets funzionano anche come contenitori (ad esempio un "QMainWindow":http://doc.qt.nokia.com/4.7/qmainwindow.html continene toolbar, menù, barre di stato ed altri widgets), ma è comunque possibile visualizzare un widget singolo nella sua finestra. I widgets sono nascosti di default: la funzione "show()":http://doc.qt.nokia.com/4.7/qwidget.html#show ha il compito di visualizzarli sul desktop.

La riga 11 avvia il ciclo di eventi di "QApplication":http://doc.qt.nokia.com/4.7/qapplication.html. Quando un programma Qt è in esecuzione, sono generati degli eventi che vengono inviati ai widgets dell'applicazione. Esempi di eventi sono pressione dei tasti del mouse o della tastiera. Quando si digita del testo nel widget di editor testuale, esso riceve eventi di pressione dei tasti e risponde visualizzando il testo digitato.

Per eseguire l'applicazione è sufficiente aprire un prompt dei comandi ed entrare nella cartella in cui risiede il file .cpp del programma. I seguenti comandi compilano l'applicazione.

 qmake -project
qmake
make

Questo crea un eseguibile nella cartella part1 (nota che su Windows si potrebbe dover utilizzare nmake al posto di make, inoltre l'eseguibile verrà posizionato nelle cartelle part1/debug o part1/release). qmake è il tool di compilazione di Qt e richiede un file di configurazione. qmake genera questo file per noi quando gli diamo come argomento "-project" . Dato un file di configurazione (con suffisso .pro), qmake crea un makefile per compilare il programma. Torneremo su come scrivere il proprio file .pro più tardi.

h3. Per approfondire

|Argomento|Collegamento| |Widgets e geomentria delle finetre| "Window and Dialog Widgets":http://doc.qt.nokia.com/4.7/application-windows.html%7C |Eventi e loro gestione|"The Event System":http://doc.qt.nokia.com/4.7/eventsandfilters.html%7C

h2. Aggiungere un bottone di uscita

Nelle applicazioni reali solitamente si utilizzano più widgets. Introdurremo ora un "QPushButton":http://doc.qt.nokia.com/4.7/qpushbutton.html al di sotto dell'editor di testo. Quando premuto (ad esempio con il mouse), il bottone permetterà di uscire dall'applicazione.

p=. gs2.png

Diamo un'occhiata al codice.

#include <QtGui>

int main(int argv, char **args)
{
 QApplication app(argv, args);

 QTextEdit textEdit;
 QPushButton quitButton("Quit");

 QObject::connect(&amp;quitButton, SIGNAL (clicked()), qApp, SLOT (quit()));

 QVBoxLayout layout;
 layout.addWidget(&amp;textEdit);
 layout.addWidget(&amp;quitButton);

 QWidget window;
 window.setLayout(&amp;layout);

 window.show();

 return app.exec();
}

La prima linea include QtGui, un'header che contiene tutte le classi delle GUI delle Qt.

La linea 10 utilizza il meccanismo di segnali e slot per far uscire l'applicazione quando il Quit button viene premuto. Uno slot è una funzione che può essere invocata a runtime utilizzando il suo nome (come stringa letterale). Un segnale è una funzione che quando chiamata invoca gli slots registrati ad esso.

"quit()":http://doc.qt.nokia.com/4.7/qcoreapplication.html#quit è uno slot di "QApplication":http://doc.qt.nokia.com/4.7/qapplication.html che chiude l'applicazione quando invocato. "clicked()":http://doc.qt.nokia.com/4.7/qabstractbutton.html#clicked è un segnale che "QPushButton":http://doc.qt.nokia.com/4.7/qpushbutton.html emette quando viene premuto. La funzione statica "QObject::connect()":http://doc.qt.nokia.com/4.7/qobject.html#connect si occupa di connettere lo slot ed il segnale. SIGNAL () e SLOT() sono due macro che richiedono i prototipi delle funzioni del segnale e dello slot al fine di connetterli. E' inoltre necessario fornire i puntatori agli oggetti che devono inviare e ricevere il segnale.

La linea 12 crea un "QVBoxLayout":http://doc.qt.nokia.com/4.7/qvboxlayout.html. Come menzionato precedentemente, i widgets possono contenere altri widgets. E' possibile impostare direttamente i limiti (locazione e dimensioni) di widget figli, ma di solito è più semplice e comodo utilizzare un layout. Un layout gestisce le dimensioni dei widget figli. "QVBoxLayout":http://doc.qt.nokia.com/4.7/qvboxlayout.html, per esempio, posiziona i widget figli in righe verticali.

Le linee 13 e 14 aggiungono al layout l'editor di testo ed il bottone, mentre la riga 17 imposta il layout sul widget.

h3. Per approfondire

|Argomento|Collegamento| |Segnali e slots|"Signals & Slots":http://doc.qt.nokia.com/4.7/signalsandslots.html%7C |Layouts|"Layout Management":http://doc.qt.nokia.com/4.7/layout.html , "Widgets and Layouts":http://doc.qt.nokia.com/4.7/widgets-and-layouts.html , "Layout Examples":http://doc.qt.nokia.com/4.7/examples-layouts.html%7C |I widgets di Qt|"Qt Widget Gallery":http://doc.qt.nokia.com/4.7/gallery.html , "Widget Examples":http://doc.qt.nokia.com/4.7/examples-widgets.html%7C

h2. Sottoclassare QWidget

Quando gli utilizzatori vogliono uscire dall'applicazione, si potrebbe voler visualizzare una finestra di dialogo per chiedere all'utente se è effettivamente convinto di voler uscire. In questo esempio, sottoclassiamo "QWidget":http://doc.qt.nokia.com/4.7/qwidget.html ed aggiungiamo uno slot che connettiamo al Quit button.

p=. gs3.png

Diamo un'occhiata al codice:

class Notepad : public QWidget
{
 Q_OBJECT

public:
 Notepad();

private slots:
 void quit();

private:
 QTextEdit *textEdit;
 QPushButton *quitButton;
};

La macro Q_OBJECT deve essere la prima nella definizione della classe e definisce questa come un QObject (è necessario che la classe erediti da "QObject":http://doc.qt.nokia.com/4.7/qobject.html). Un "QObject":http://doc.qt.nokia.com/4.7/qobject.html aggiunge molte capacità ad una normale classe C++. In particolare, il nome della classe e degli slots può essere recuperato a tempo di esecuzione. E' inoltre possibile invocare direttamente uno slot o recuperare i tipi dei suoi paramentri.

La linea 13 dichiara lo slot quit() . Utilizzando la macro slots, ciò diventa molto semplice. Lo slot quit() può ora essere connesso ad un segnale che possiede un prototipo compatibile (in questo caso, ogni segnale che non prende parametri).

Piuttosto che impostare la GUI e connettere lo slot nella funzione main(), utilizziamo ora il costruttore della classe Notepad.

Notepad::Notepad()
{
 textEdit = new QTextEdit;
 quitButton = new QPushButton(tr("Quit"));

 connect(quitButton, SIGNAL (clicked()), this, SLOT (quit()));

 QVBoxLayout *layout = new QVBoxLayout;
 layout->addWidget(textEdit);
 layout->addWidget(quitButton);

setLayout(layout);

setWindowTitle(tr("Notepad"));
}

Come si può vedere nella definizione della classe, utilizziamo puntatori ai nostri "QObject":http://doc.qt.nokia.com/4.7/qobject.html (textEdit e quitButton). Come regole, si dovrebbe sempre allocare i "QObject":http://doc.qt.nokia.com/4.7/qobject.html nella memoria heap e mai copiarli.

Utilizziamo anche la funzione "tr()":http://doc.qt.nokia.com/4.7/qobject.html#tr attorno alle stringhe da visualizzare all'utente. Questa funzione è necessaria quando si vuole distribuire l'applicazione in più di una lingua (ad esempio Inglese ed Italiano). Qui non entreremo nei detagli, ma è possibile seguire il link Qt Linguist degli approfondimenti.

Per approfondire

Argomento	Collegamento
tr() e internazionalizzazione	"Qt Linguist Manual":http://doc.qt.nokia.com/4.7/linguist-manual.html , "Writing Source Code for Translation":http://doc.qt.nokia.com/4.7/i18n-source-translation.html , "Hello tr() Example":http://doc.qt.nokia.com/4.7/linguist-hellotr.html , "Internationalization with Qt":http://doc.qt.nokia.com/4.7/internationalization.html
QObjects ed il modello a oggeti di Qt (essenziale per comprendere Qt)	"Object Model":http://doc.qt.nokia.com/4.7/object.html
qmake ed il sistema di compilazione di Qt	"qmake Manual":http://doc.qt.nokia.com/4.7/qmake-manual.html

Creare un file .pro

Per questo esempio scriveremo il nostro file .pro al posto di utilizzare l'opzione _-project_ di qmake.

HEADERS = notepad.h
SOURCES = notepad.cpp  main.cpp

I seguenti comandi console compilano il programma.

qmake
make

h2. Usare una QMainWindow

Molte applicazioni trarranno beneficio dall'ultilizzo di "QMainWindow":http://doc.qt.nokia.com/4.7/qmainwindow.html, poiché posiede il proprio layout a cui si può aggiungere una barra dei menù, dock widgets, tool bars e una barra di stato. "QMainWindow":http://doc.qt.nokia.com/4.7/qmainwindow.html ha un'area centrale che può essere occupata da ogni tipo di widget. Nel nostro caso posizioneremo qui il nostro editor di testo.

p=. gs4.png

Guardiamo la nuova definizione della classe Notepad.

#include <QtGui>

class Notepad : public QMainWindow
{
 Q_OBJECT

public:
 Notepad();

private slots:
 void open();
 void save();
 void quit();

private:
 QTextEdit *textEdit;

 QAction *openAction;
 QAction *saveAction;
 QAction *exitAction;

 QMenu *fileMenu;
};

Includiamo altri due slots per salvare ed aprire un documento. Li implementeremo nella prossima sezione.

Solitamente in una main window lo stesso slot può essere invocato da vari widgets. Sono esempi gli elementi del menù ed i bottoni nella tool bar. Per semplificare ciò, Qt fornisce "QAction":http://doc.qt.nokia.com/4.7/qaction.html, una classe che può essere data a vari widgets e connessa ad uno slot. Per esempio, "QMenu":http://doc.qt.nokia.com/4.7/qmenu.html e "QToolBar":http://doc.qt.nokia.com/4.7/qtoolbar.html possono creare elementi del menù e tool buttons dalle stesse "QActions":http://doc.qt.nokia.com/4.7/qaction.html. Presto vedremo in che modo.

Come prima, useremo il costruttore della classe Notepad per impostare la GUI.

Notepad::Notepad()
{
 saveAction = new QAction(tr("&Open"), this);
 saveAction = new QAction(tr("&Save"), this);
 exitAction = new QAction(tr("E&xit"), this);

 connect(openAction, SIGNAL (triggered()), this, SLOT (open()));
 connect(saveAction, SIGNAL (triggered()), this, SLOT (save()));
 connect(exitAction, SIGNAL (triggered()), qApp, SLOT (quit()));

 fileMenu = menuBar()->addMenu(tr("&File"));
 fileMenu->addAction(openAction);
 fileMenu->addAction(saveAction);
 fileMenu->addSeparator();
 fileMenu->addAction(exitAction);

textEdit = new QTextEdit;
 setCentralWidget(textEdit);

setWindowTitle(tr("Notepad"));
}

Le "QActions":http://doc.qt.nokia.com/4.7/qaction.html sono create con il testo che dovrebbe apparire sui widgets a cui vengono aggiunte (nel nostro caso gli elementi del menù). Se inoltre volessimo aggiungerle ad una tool bar potremmo impostare delle "icone":http://doc.qt.nokia.com/4.7/qicon.html alle varie azioni.

Quando un elemento del menù è cliccato, esso attiva la "QAction":http://doc.qt.nokia.com/4.7/qaction.html che si occupa di invocare il rispettivo slot.

Per approfondire

Argomento	Collegamento
Main windows e classi main window	"Application Main Window":http://doc.qt.nokia.com/4.7/mainwindow.html , "Main Window Examples":http://doc.qt.nokia.com/4.7/examples-mainwindow.html
Applicazioni MDI	"QMdiArea":http://doc.qt.nokia.com/4.7/qmdiarea.html , "MDI Example":http://doc.qt.nokia.com/4.7/mainwindows-mdi.html

Salvataggio e caricamento

In questo esempio implementeremo la funzionalità degli slot di open() e save() che abbiamo aggiunto nella sezione precedente.

p=. gs5.png

Iniziamo con lo slot open():

QString fileName = QFileDialog::getOpenFileName(this, tr("Open File"), "",
 tr("Text Files ('''.txt);;C++ Files ('''.cpp '''.h)"));

if (fileName != "") {
 QFile file(fileName);
 if (!file.open(QIODevice::ReadOnly)) {
 QMessageBox::critical(this, tr("Error"),
 tr("Could not open file"));
 return;
 }
 QString contents = file.readAll().constData();
 textEdit->setPlainText(contents);
 file.close();
}

Il primo passo è chiedere all'utente il nome del file da aprire. Qt contiene "QFileDialog":http://doc.qt.nokia.com/4.7/qfiledialog.html, una finestra di dialogo dalla quale l'utente può selezionare un file. L'immagine precedente mostra un esempio da Kubuntu. La funzione statica "getOpenFileName()":http://doc.qt.nokia.com/4.7/qfiledialog.html#getOpenFileName visualizza una finestra di dialogo modale e non ritorna fintanto che l'utente non seleziona un file. La funzione ritorna una stringa contenente il path del file selezionato, oppure una stringa vuota nel caso l'utente annulli l'operazione.

Se otteniamo il nome di un file, proviamo ad aprirlo tramite la funzione "open()":http://doc.qt.nokia.com/4.7/qiodevice.html#open, che ritorna true se il file può essere aperto. Qui non andremo nel dettaglio della gestione errori, ma è possibile seguire il link dalla sezione approondimenti. Se il file non può essere aperto, utilizziamo una "QMessageBox":http://doc.qt.nokia.com/4.7/qmessagebox.html per visualizzare una finestra con un messaggio d'errore (vedere la descrizione della classe "QMessageBox":http://doc.qt.nokia.com/4.7/qmessagebox.html per ulteriori dettagli).

La lettura dei dati è banale, grazie alla funzione "readAll()":http://doc.qt.nokia.com/4.7/qiodevice.html#readAll che ritorna tutti i dati nel file in un "QByteArray":http://doc.qt.nokia.com/4.7/qbytearray.html. La funzione "constData()":http://doc.qt.nokia.com/4.7/qbytearray.html#constData ritorna il contenuto dell'array sotto forma di const char, per il quale "QString":http://doc.qt.nokia.com/4.7/qstring.html ha un costrutture. Il contenuto ora può essere visualizzato nell'editor di testo. Possiamo ora chudere il file con "close()":http://doc.qt.nokia.com/4.7/qiodevice.html#close per far ritornare il file descriptor al sistema operativo.

Adesso spostiamoci sullo slot save().

QString fileName = QFileDialog::getSaveFileName(this, tr("Save File"), "",
 tr("Text Files ('''.txt);;C++ Files ('''.cpp '''.h)"));

if (fileName != "") {
 QFile file(fileName);
 if (!file.open(QIODevice::WriteOnly)) {
 // error message
 } else {
 QTextStream stream(&file);
 stream << textEdit->toPlainText();
 stream.flush();
 file.close();
 }
}

Quando scriviamo il contenuto dell'editor di testo nel file, utilizziamo una classe "QTextStream":http://doc.qt.nokia.com/4.7/qtextstream.html che utilizza un oggetto "QFile":http://doc.qt.nokia.com/4.7/qfile.html. La text stream può scrivere stringe direttamente nel file, mentre "QFile":http://doc.qt.nokia.com/4.7/qfile.html accetta solo dati grezzi (char) nella funzione "write()":http://doc.qt.nokia.com/4.7/qiodevice.html#write di "QIODevice":http://doc.qt.nokia.com/4.7/qiodevice.html.

Per approfondire

Argomento	Collegamento
Files e dispositivi di I/O	"QFile":http://doc.qt.nokia.com/4.7/qfile.html , "QIODevice":http://doc.qt.nokia.com/4.7/qiodevice.html