Guida introduttiva alla programmazione con QML

This article may require cleanup to meet the Qt Wiki's quality standards. Reason: Auto-imported from ExpressionEngine. Please improve this article if you can. Remove the {{cleanup}} tag and add this page to Updated pages list after it's clean.

Guida introduttiva alla programmazione con QML

Benvenuto nel mondo di QML, il linguaggio dichiarativo per interfacce utente (UI: User Interface). In questa guida introduttiva, creeremo un semplice editor di testo utilizzando QML. Dopo la lettura di questa guida, dovresti essere in grado di sviluppare le tue applicazioni utilizzando QML e Qt C+.

QML per la costruzione di interfacce utente

p. L'applicazione che stiamo costruendo è un semplice editor di testo per caricare, salvare ed modificare del testo. Questa guida sarà composta di due parti. La prima parte prevede la progettazione della disposizione (layout) e dei comportamenti dei componenti dell'applicazione, tramite il linguaggio dichiarativo QML. Nella seconda parte procederemo allo sviluppo delle componenti per il caricamento e il salvataggio dei file utilizzando Qt C. Tramite l'utilizzo del Qt Meta-Object System, siamo in grado di esporre le funzioni C+ come proprietà che gli elementi QML potranno utilizzare in modo nativo. In questo modo, utilizzando QML e Qt C+, possiamo separare, in modo molto efficace, la logica di interfaccia dalla logica dell'applicazione.

p. Per eseguire il codice QML dell'esempio, è sufficente passare al programma qmlviewer il nome del file QML come argomento. La parte C+ di questa esercitazione presuppone che il lettore possieda una conoscenza di base delle procedure di compilazione di Qt.

Capitoli dell'esercitazione:

1. Definire un pulsante e un menu
2. Implementare una barra dei menu
3. Costruire un editor di testo
4. Decorare l'editor di testo
5. Estendere QML usando Qt C++

Definire un Pulsante e un Menu

Componenti di Base - un Pulsante

Iniziamo il nostro editor di testo con la costruzione di un pulsante. Funzionalmente, un pulsante è costituito da una zona sensibile ad azioni esterne (del mouse o di un'interfaccia touch screen per esempio) e da una etichetta. I pulsanti eseguono delle azioni ogniqualvolta l'utente preme il pulsante.

In QML, l'elemento visuale di base è il rettangolo (Rectangle). L'elemento Rectangle ha delle proprietà che permettono di controllare l'aspetto dell'elemento e la sua posizione.

 import Qt 4.7

Rectangle{
 id:simplebutton

color: "grey"
 width: 400; height: 400

Text {
 id: buttonLabel
 text: "button label"
 anchors.centerIn:parent
 }
 }

Per prima cosa, nel codice, l'istruzione import Qt 4.7, permette al programma qmlviewer di importare gli elementi QML che useremo in seguito. Questa prima istruzione deve esistere in ogni file QML. Si noti che la versione dei moduli Qt è parte integrante della dichiarazione di importazione.

Questo semplice rettangolo possiede un identificatore univoco, simplebutton, che è associato alla proprietà id. Le proprietà dell'elemento Rectangle sono collegate ai relativi valori in questo modo: elencando il nome della proprietà, seguito da due punti, quindi il suo valore. Nel codice di esempio, il colore grey è legato alla proprietà color del rettangolo. Nello stesso modo colleghiamo le proprietà width (larghezza) e height (altezza) del rettangolo.

L'elemento Text è un campo di testo non modificabile. Chiamiamo buttonLabel questo elemento Text. Per impostare il contenuto della stringa del campo di testo, associamo un valore alla proprietà text. E' utile far notare che l'elemento QML Text e la sua proprietà text sono entità ben distinte. L'etichetta è contenuta all'interno del rettangolo e, al fine di centrarla nel mezzo, colleghiamo gerarchicamente le anchors (ancore) dell'elemento Text al suo genitore, che nel nostro caso si chiama simplebutton. Ogni ancora può essere collegata alle ancore di altri elementi, in questo modo si semplifica la definizione della disposizione reciproca degli elementi.

Salviamo questo codice come SimpleButton.qml. Se lanciamo il programma qmlviewer con il nome del file come argomento, vedremo visualizzato il rettangolo grigio con una etichetta di testo.

Per implementare la funzionalità collegata al click sul pulsante, utilizziamo la gestione degli eventi di QML. La gestione degli eventi di QML è molto simile al meccanismo signal e slot di Qt. Ogni qualvolta viene invocato una signal, viene chiamato il corrispondente slot collegato.

Rectangle{
 id:simplebutton
 …

MouseArea{
 id: buttonMouseArea

anchors.fill: parent //anchor all sides of the mouse area to the rectangle's anchors
 //onClicked handles valid mouse button clicks
 onClicked: console.log(buttonLabel.text + " clicked" )
 }
}

Aggiungiamo un elemento MouseArea nel nostro componente simpleButton. Gli elementi che compongono la nostra MouseArea descrivono l'area interattiva in cui vengono rilevati i movimenti del mouse. Nel nostro caso, per il nostro pulsante, 'ancoriamo' l'intera MouseArea al suo genitore, che è simpleButton. La sintassi anchors.fill è un modo di esprimere l'accesso, nel nostro caso, ad una proprietà specifica denominata fill all'interno di un gruppo di proprietà denominato anchors. QML utilizza layout basati su ancore, in cui ciascun elemento può ancorarsi ad un altro elemento, in questo modo si creano layout robusti e flessibili.

L'elemento MouseArea prevede molti gestori di segnali (signal handler) che vengono chiamati durante i movimenti del mouse all'interno dei suoi confini specificati. Uno di questi è onClicked ed è chiamato ogni volta che il previsto pulsante del mouse viene cliccato, nel nostro caso il click sinistro è l'azione di default. Possiamo legare delle azioni al gestore dell'evento onClicked. Nel nostro esempio, la chiamata a console.log () emette una stringa di testo ogni volta che l'area attiva viene cliccata. La funzione console.log è un strumento molto utile per il debugging e, in generale, per l'output di testo dell'applicazione.

Il codice in SimpleButton.qml è già sufficiente per visualizzare un pulsante sullo schermo e produrre del testo, ogni volta che lo si clicca con il mouse.

Rectangle {
 id:Button
 …

property color buttonColor: "lightblue"
 property color onHoverColor: "gold"
 property color borderColor: "white"

signal buttonClick()
 onButtonClick: {
 console.log(buttonLabel.text + " clicked" )
 }

MouseArea{
 onClicked: buttonClick()
 hoverEnabled: true
 onEntered: parent.border.color = onHoverColor
 onExited: parent.border.color = borderColor
 }

//determines the color of the button by using the conditional operator
 color: buttonMouseArea.pressed ? Qt.darker(buttonColor, 1.5) : buttonColor
}

Nel file Button.qml abbiamo il codice per un pulsante completamente funzionante. I frammenti di codice riportati in questo articolo, hanno alcune parti omesse, indicate con dei puntini di sospensione, perché o erano già stati introdotti in precedenza o perché non rilevanti per la discussione di questo codice specifico.

Per dichiarare delle proprietà personalizzate, si utilizza una sintassi del tipo proprietà tipo nome. Nel nostro codice viene dichiarata la proprietà buttonColor, di tipo color, e collegata al valore "lightblue". La proprietà buttonColor è poi utilizzata in un'operazione condizionale per determinare il colore di riempimento dei pulsanti. Si noti che l'assegnazione del valore della proprietà è possibile sia con il segno di uguale =, sia con l'operatore due punti :. Le proprietà personalizzate permettono di rendere accessibili elementi interni dell'elemento Rectangle, anche dall'esterno del suo campo di applicazione (scope). Ci sono diversi tipi QML di base come int, string, real, così come un tipo generico chiamato variant.

Collegando i gestori di segnale onEntered e onExited ai colori, è possibile rendere il bordo del pulsante giallo quando il mouse passa sopra il pulsante e ripristinare il colore precedente quando il mouse lascia la sua zona sensibile (MouseArea).

Viene dichiarato un signal buttonClick(), inserendo la keyword signal davanti al nome della funzione. Per ogni signal vengono creati automaticamente le relative funzioni di gestione, i loro nomi iniziano con il prefisso on. Di conseguenza, la funzione onButtonClick è il gestore (handler) di buttonClick. Succesivamente a onButtonClick viene quindi assegnata l'operazione da eseguire. Nel nostro pulsante di esempio, il gestore di mouse onClicked chiama semplicemente onButtonClick, che visualizza un testo. La funzione onButtonClick permette ad oggetti esterni di accedere facilmente alla mouse area del pulsante. Inoltre, gli oggetti possono avere più di una dichiarazione di MouseArea e avere un signal ButtonClick può migliorare la distinzione tra i diversi gestori di segnali della MouseArea.

Adesso abbiamo le conoscenze di base che ci permettono l'implementazione di elementi in QML in grado di gestire i principali movimenti del mouse. Abbiamo creato una etichetta di tipo Text all'interno di un elemento Rectangle, personalizzato le sue proprietà e implementato dei comportamenti che rispondono ai movimenti del mouse. Questa idea di base della creazione di elementi all'interno di altri elementi, si ripresenterà nello sviluppo di tutta questa applicazione di esempio.

Questo pulsante non è molto utile se non viene utilizzato come componente per eseguire qualche azione. Nella sezione successiva, vedremo come creare un menu che utilizza alcuni di questi pulsanti.

Creazione di un Menu

Fino ad ora, abbiamo spiegato come creare degli elementi e definirne i comportamenti all'interno di un singolo file QML. In questa sezione ci occuperemo di come importare elementi QML e come riutilizzare alcuni componenti già realizzati per costruire altri componenti.

Un Menu permette di visualizzare il contenuto di una lista, ogni elemento ha la capacità di eseguire un'azione. In QML, possiamo ottenere un menu in diversi modi. Per prima cosa, creiamo un menu contenente dei pulsanti cui faremo eseguire opportune azioni. Il codice del menu è nel file FileMenu.qml.

 import Qt 4.7 import the main Qt QML module
 import "folderName" import the contents of the folder
 import "script.js" as Script import a Javascript file and name it as Script

La sintassi riportata sopra mostra alcuni utilizzi della keyword import. Questo è necessario per poter utilizzare dei file JavaScript, o dei file QML che non sono presenti all'interno della directory corrente. Poiché Button.qml è nella stessa directory di FileMenu.qml, non abbiamo la necessità di importare esplicitamente il file Button.qml per poterlo usare. Possiamo creare direttamente un elemento Button di tipo Button{}, allo stesso modo di un Rectangle{}.

 In FileMenu.qml:

Row{
 anchors.centerIn: parent
 spacing: parent.width/6

Button{
 id: loadButton
 buttonColor: "lightgrey"
 label: "Load"
 }
 Button{
 buttonColor: "grey"
 id: saveButton
 label: "Save"
 }
 Button{
 id: exitButton
 label: "Exit"
 buttonColor: "darkgrey"

onButtonClick: Qt.quit()
 }
 }

Nel FileMenu.qml, sono dichiariati tre elementi Button. Questi sono dichiarati all'interno di un elemento di tipo Row, un elemento di posizionamento che allinea i suoi figli lungo una fila verticale. La dichiarazione di Button risiede nel file Button.qml, che è lo stesso file che abbiamo usato per la sezione precedente. E' possibile definire dei nuovi collegamenti per le proprietà dei pulsanti appena creati, in questo modo si sovrascrivono le proprietà impostate in Button.qml. Il pulsante denominato ExitButton, quando viene cliccato, fa in modo che la finestra dell'applicazione venga abbandonata e chiusa. E' bene tenere presente che il gestore di segnale onButtonClick nel file Button.qml viene chiamato in aggiunta al gestore onButtonClick di ExitButton.

L'elemeto Row è dichiarato all'interno di un Rectangle, creando un contenitore rettangolare per la fila dei pulsanti. Questo rettangolo aggiuntivo permette di avere un modo indiretto di organizzare la fila dei pulsanti all'interno del menu.

La dichiarazione del menu Modifica (Edit) è molto simile a quanto già visto finora. Il menu è composto da pulsanti che hanno le etichette: Copy (Copia), Paste (Incolla) e Select All (Seleziona tutto).

Grazie alla conoscenza di importazione e personalizzazione dei componenti acquisita finora, possiamo ora combinare queste pagine di menu per creare una barra dei menu, composta da pulsanti per selezionare i menu specifici e quindi passare a vedere come possiamo strutturare i dati utilizzando QML.

Implementare una barra dei menu

Il nostro editor di testo potrà visualizzare i menu disponibili attraverso una barra dei menu. La barra dei menu proporrà i diversi menu e l'utente sceglierà quali menu visualizzare. La funzionalità di cambio dei menu implica che i questi avranno bisogno di una struttura più sofisticata di quella che si limita a mostrarli su di una riga. QML utilizza modelli e viste per gestire e visualizzare i dati strutturati.

Utilizzare modelli dati e viste

QML dispone di diverse viste (data views) che visualizzano i modelli dati (data models). La nostra barra dei menu visualizza i menu in una lista, con una testata che mostra una fila di nomi di menu. L'elenco dei menu è dichiarata all'interno di un VisualItemModel. L'elemento VisualItemModel contiene elementi che dispongono già di viste come elementi Rectangle e altri elementi d'interfaccia. Altri tipi di modelli, come l'elemento ListModel, hanno bisogno di un elemento delegato (delegate) per visualizzare i propri dati.

In questo caso sono dichiarati due elementi visuali in menuListModel, il FileMenu e l'EditMenu, e sono visualizzati e personalizzati tramite un controllo ListView. Il file MenuBar.qml contiene le dichiarazioni QML e un semplice menu modifica è definito in EditMenu.qml.

 VisualItemModel{
 id: menuListModel
 FileMenu{
 width: menuListView.width
 height: menuBar.height
 color: fileColor
 }
 EditMenu{
 color: editColor
 width: menuListView.width
 height: menuBar.height
 }
 }

L'elemento ListView visualizza un modello attraverso un elemento delegato. Il delegato può dichiarare che gli elementi del modello siano visualizzati in un elemento di tipo Row o siano posti in una griglia. Nel nostro caso menuListModel ha già gli elementi visibili, quindi, non abbiamo bisogno di dichiarare un delegato.

 ListView{
 id: menuListView

//Anchors are set to react to window anchors
 anchors.fill:parent
 anchors.bottom: parent.bottom
 width:parent.width
 height: parent.height

//the model contains the data
 model: menuListModel

//control the movement of the menu switching
 snapMode: ListView.SnapOneItem
 orientation: ListView.Horizontal
 boundsBehavior: Flickable.StopAtBounds
 flickDeceleration: 5000
 highlightFollowsCurrentItem: true
 highlightMoveDuration:240
 highlightRangeMode: ListView.StrictlyEnforceRange
 }

Inoltre, ListView deriva da Flickable, facendo così in modo l'elenco risponda al trascinamento con il mouse (drag) e altri eventi (gestures). L'ultima parte del codice di cui sopra imposta le proprietà di Flickable per ottenere il movimento desiderato sfogliando la nostra vista. Nello specifico, la proprietà highlightMoveDuration cambia la durata della transizione nello sfoglio. Un valore più alto di highlightMoveDuration causa un passaggio più lento tra i menu.

La ListView getisce gli elementi del modello attraverso un index (indice) e ogni elemento visual nel modello è accessibile tramite questo indice, secondo l'ordine di dichiarazione. Modificare il currentIndex ha come effetto quello di cambiare l'elemento evidenziato nella ListView. L'intestazione nella nostra barra dei menu esemplifica questo effetto. Ci sono due pulsanti nella riga, entrambi cambiano il menu corrente quando vengono cliccati. Il pulsante fileButton cambia il menu corrente nel menu file quando viene cliccato, l'indice in questo caso è 0, perché FileMenu è dichiarato per primo nella menuListModel. Analogamente, il pulsante editButton, quando viene cliccato, cambierà il menù corrente nel menu EditMenu.

Il rettangolo labelList ha valore di z di 1, questo indica che è visualizzato davanti alla barra dei menu. Gli elementi con valori di z maggiori sono visualizzati davanti a oggetti con valori più bassi di z. Il valore di default di z è 0.

 Rectangle{
 id: labelList
 …
 z: 1
 Row{
 anchors.centerIn: parent
 spacing:40
 Button{
 label: "File"
 id: fileButton
 …
 onButtonClick: menuListView.currentIndex = 0
 }
 Button{
 id: editButton
 label: "Edit"
 …
 onButtonClick: menuListView.currentIndex = 1
 }
 }
 }

La barra dei menu che abbiamo appena creato può essere sfogliata per accedere ai menu oppure si può cliccare sui nomi dei menu nella barra in alto. La commutazione delle schermate dei menu è intuitiva e immediata per l'utente.

Costruire un Editor di testo

Dichiarare una TextArea

Il nostro editor di testo non può essere un editor di testo finché non contiene una zona di testo modificabile. L'elemento TextEdit di QML permette proprio la dichiarazione di un componente per la modifica di testo multi-linea. TextEdit è diverso da un elemento di tipo Text, che non consente all'utente di modificare direttamente il testo.

 TextEdit{
 id: textEditor
 anchors.fill:parent
 width:parent.width; height:parent.height
 color:"midnightblue"
 focus: true

wrapMode: TextEdit.Wrap

onCursorRectangleChanged: flickArea.ensureVisible(cursorRectangle)
 }

Nell'editor sono impostate le proprietà color del proprio font e del testo a capo (wrap). L'area di TextEdit è all'interno di un area mobile che farà scorrere il testo, se il cursore del testo è al di fuori dell'area visibile. La funzione EnsureVisible() controlla se il rettangolo del cursore si trova al di fuori dei confini visibili e, nel caso, sposta opportunamente l'area di testo. QML utilizza la sintassi Javascript per i suoi script e, come accennato in precedenza, i file Javascript possono essere importati e utilizzati all'interno di un file QML.

 function ensureVisible®{
 if (contentX >= r.x)
 contentX = r.x;
 else if (contentX+width <= r.x+r.width)
 contentX = r.x+r.width-width;
 if (contentY >= r.y)
 contentY = r.y;
 else if (contentY+height <= r.y+r.height)
 contentY = r.y+r.height-height;
 }

Combinare componenti per l'editor di testo

Ora siamo pronti per creare il layout del nostro editor di testo utilizzando QML. L'editor di testo ha due componenti, la barra dei menu che abbiamo creato e l'area di testo. QML ci permette di riutilizzare i componenti, rendendo quindi il nostro codice più semplice, mediante l'importazione di componenti e la personalizzazione quando ciò sia necessario. Il nostro editor di testo ha la propria finestra divisa in due parti: un terzo dello schermo è dedicata alla barra dei menu e i rimanenti due terzi della schermata al testo. La barra dei menu viene visualizzata davanti a ogni altro elemento.

 Rectangle{

id: screen
 width: 1000; height: 1000

//the screen is partitioned into the MenuBar and TextArea. 1/3 of the screen is assigned to the MenuBar
 property int partition: height/3

MenuBar{
 id:menuBar
 height: partition
 width:parent.width
 z: 1
 }

TextArea{
 id:textArea
 anchors.bottom:parent.bottom
 y: partition
 color: "white"
 height: partition*2
 width:parent.width
 }
 }

Tramite 'importazione di componenti riutilizzabili, il codice del nostro TextEditor appare molto più semplice. Si può quindi personalizzare l'applicazione principale, senza preoccuparsi delle proprietà che hanno già un comportamenti definito. Usando questo approccio, i layout delle applicazioni e i componenti di interfaccia utente possono essere assemblati più facilmente.

Abbellire l'editor di testo

Implementare una interfaccia a scomparsa

Il nostro editor di testo appare semplice e abbiamo bisogno di abbellirlo. Utilizzando QML, possiamo dichiarare delle transizioni e animare la nostra applicazione. La nostra barra dei menu occupa un terzo dello schermo, sarebbe bello fare in modo che appaia solo quando lo vogliamo.

A tale scopo possiamo aggiungere un elemento di interfaccia (drawer) che si occuperà di contrarre o espandere la barra dei menu quando viene cliccata. Nella nostra caso, abbiamo un piccolo rettangolo che risponde ai clic del mouse. Questo elemento, così come l'applicazione, ha due stati: lo stato "drawer aperto" e lo stato "drawer chiuso". L'elemento drawer è una sottile striscia rettangolare con all'interno un elemento Imagine che definisce un'icona di una freccia centrata all'interno dell'area. Il drawer assegna uno stato all'intera applicazione, attraverso l'identificatore screen, volta che un utente clicca sulla mouse area.

 Rectangle{
 id:drawer
 height:15

Image{
 id: arrowIcon
 source: "images/arrow.png"
 anchors.horizontalCenter: parent.horizontalCenter
 }

MouseArea{
 id: drawerMouseArea
 anchors.fill:parent
 onClicked:{
 if (screen.state  "DRAWER_CLOSED"){
                     screen.state = "DRAWER_OPEN"
                 }
                 else if (screen.state  "DRAWER_OPEN"){
 screen.state = "DRAWER_CLOSED"
 }
 }
 …
 }
 }

Uno stato è semplicemente un insieme di configurazioni predefinite e si dichiara tramite un elemento di tipo State. Un lista di stati possono essere collegati alla proprietà states e successivamente iterati. Nella nostra applicazione, i due stati sono chiamati DRAWER_CLOSED e DRAWER_OPEN. Tramite i PropertyChanges sono definite le nuove configurazioni degli elementi. Nello stato DRAWER_OPEN, ci sono quattro elementi che riceveranno delle modifiche alle proprietà. Il primo, menuBar, cambierà la sua proprietà y in 0. Analogamente, la textArea si abbasserà in una nuova posizione quando lo stato è DRAWER_OPEN. Anche la textarea, il drawer, e la sua icona subiranno dei cambiamento delle loro proprietà per adeguarsi allo stato corrente.

 states:[
 State {
 name: "DRAWER_OPEN"
 PropertyChanges { target: menuBar; y: 0}
 PropertyChanges { target: textArea; y: partition + drawer.height}
 PropertyChanges { target: drawer; y: partition}
 PropertyChanges { target: arrowIcon; rotation: 180}
 },
 State {
 name: "DRAWER_CLOSED"
 PropertyChanges { target: menuBar; y:-height; }
 PropertyChanges { target: textArea; y: drawer.height; height: screen.height- drawer.height }
 PropertyChanges { target: drawer; y: 0 }
 PropertyChanges { target: arrowIcon; rotation: 0 }
 }
 ]

I cambiamenti di stato sono in genere repentini e c'è l'esigenza di smorzare le transizioni. Le transizioni tra gli stati sono definite utilizzando l'elemento Transition, che può essere associato alla proprietà transitions di un elemento. Nel nostro editor di testo avviene una transizione di stato ogni volta che il suo stato diventa o DRAWER_OPEN o DRAWER_CLOSED. È importante sottolineare che una transizione ha di solito bisogno di definire uno stato from e uno to, ma nel nostro caso, possiamo usare il simbolo jolly (wild card) * per indicare che la transizione si applica a tutti i cambiamenti di stato.

Durante le transizioni, possiamo assegnare delle animazioni ai cambiamenti di proprietà. La nostra menuBar cambia di posizione da y: 0 a Y:-partition ed è possibile animare questa transizione utilizzando l'elemento NumberAnimation. Possiamo definire che le proprietà degli elementi interessati, si animeranno per un certo periodo di tempo e con una certa curva di andamento (easing curve). Una curva di andamento controlla la frequenza di animazione e il comportamento dell'interpolazione durante le transizioni di stato. La curva di andamento che abbiamo scelto è Easing.OutQuint, che rallenta il movimento verso la fine dell'animazione. Potete approfondire l'argomento nell'articolo QML's Animation.

 transitions: [
 Transition {
 to: "*"
 NumberAnimation { target: textArea; properties: "y, height"; duration: 100; easing.type:Easing.OutExpo }
 NumberAnimation { target: menuBar; properties: "y"; duration: 100; easing.type: Easing.OutExpo }
 NumberAnimation { target: drawer; properties: "y"; duration: 100; easing.type: Easing.OutExpo }
 }
 ]

Un altro modo per animare il cambiamento dei valori delle proprietà è dichiarare un elemento Behavior. Una transizione funziona solo durante i cambiamenti di stato e un elemento Behavior può impostare un'animazione per un modifica generica della proprietà. Nell'editor di testo, l'icona freccia utilizza una NumberAnimation per animare la sua proprietà rotation (rotazione) ad ogni cambiamento.

 In TextEditor.qml:

Behavior{
 NumberAnimation{property: "rotation";easing.type: Easing.OutExpo }
 }

Tornando ai nostri componenti, tramite l'utilizzo di stati e animazioni, possiamo migliorare l'aspetto di questi elementi. In Button.qml, potremmo aggiungere delle modifiche alle proprietà color e scale quando il pulsante viene premuto. I tipi colore sono animati utilizzando ColorAnimation ed i numeri sono animati utilizzando NumberAnimation. La sintassi on propertyName visualizzata più sotto è comoda quando si agisce su di una singola proprietà.

 In Button.qml:
 …

color: buttonMouseArea.pressed ? Qt.darker(buttonColor, 1.5) : buttonColor
 Behavior on color { ColorAnimation{ duration: 55} }

scale: buttonMouseArea.pressed ? 1.1 : 1.00
 Behavior on scale { NumberAnimation{ duration: 55} }

Oltre a questo, possiamo intervenire sull'aspetto dei nostri componenti QML con l'aggiunta di effetti di colore, come sfumature ed effetti di trasparenza. Dichiarando un elemento Gradient si sovrascrive la proprietà color dell'elemento. Si può quindi dichiarare il colore della sfumatura utilizzando l'elemento GradientStop. La sfumatura è valorrizata utilizzando una scala tra 0,0 e 1,0.

 In MenuBar.qml
 gradient: Gradient {
 GradientStop { position: 0.0; color: "#8C8F8C" }
 GradientStop { position: 0.17; color: "#6A6D6A" }
 GradientStop { position: 0.98;color: "#3F3F3F" }
 GradientStop { position: 1.0; color: "#0e1B20" }
 }

Questo gradiente è utilizzato dalla barra dei menu per visualizzare un gradiente che simula la profondità. Il primo colore è utilizzato al valore 0,0 e l'ultimo a 1.0.

Prossimi passi

Abbiamo così finito di costruire l'interfaccia utente di un semplice editor di testo. Andando avanti, completata l'interfaccia utente, siamo in grado di implementare la logica dell'applicazione con Qt e C+. Come abbiamo visto QML funziona bene come strumento di prototipazione, separando efficacemente la logica applicativa dalla progettazione dell'interfaccia utente.

Estendere QML usando Qt C+

Ora che abbiamo il layout del nostro editor di testo, possiamo ora implementare le funzionalità dell'editor in C+. L'utilizzo di QML con C+ permette di realizzare la logica della nostra applicazione utilizzando Qt. Siamo in grado di creare un context QML in una applicazione C++ usando le classi dichiarative di Qt e visualizzare gli elementi QML tramite una Graphic Scene. In alternativa, possiamo esportare il nostro codice C++ compilato in un plugin che il programma qmlviewer è in grado di leggere. Per la nostra applicazione, implementeremo le funzioni in C++ per caricare e salvare i file e le esporteremo come plugin. In questo modo, abbiamo solo bisogno di lanciare il file QML direttamente anziché eseguire un file eseguibile.

Esportare classi C++ per QML

Vogliamo implementare le funzioni di caricamento e salvataggio file utilizzando Qt e C+. Le classi e le funzioni C+ possono essere utilizzate in QML previa una loro registrazione. La classe ha inoltre bisogno di essere compilata come un plugin Qt e il file QML avrà bisogno di sapere dove si trova il plugin nel file system.

Per la nostra applicazione, abbiamo bisogno di creare i seguenti oggetti:

1. una classe Directory che consenta di gestire le operazioni sulle directory (cartelle)
2. una classe File che sia un QObject, che simuli l'elenco dei file in una directory
3. una classe plugin che registri la classe nel corretto contesto QML
4. un file di progetto (project file) Qt per compilare il plugin
5. in file qmldir per indicare al programma qmlviewer dove trovare il plugin

Costruire un pugin Qt

Per costruire un plugin, è necessario impostare le direttive che seguono in project file Qt. Innanzi tutto vanno specificati i file contenenti i sorgenti e i file di include, nonché i moduli Qt utilizzati. Tutti i file sorgenti C++ e di progetto si trovano nella directory FileDialog.

 In cppPlugins.pro:

TEMPLATE = lib
 CONFIG ''= qt plugin
 QT''= declarative

DESTDIR ''= ../plugins
 OBJECTS_DIR = tmp
 MOC_DIR = tmp

 TARGET = FileDialog

 HEADERS''= directory.h  file.h  dialogPlugin.h

SOURCES += directory.cpp  file.cpp  dialogPlugin.cpp

Nello specifico, compiliamo con il modulo Qt declarative e lo configuriamo come un plugin, che necessita di un modello (template) di tipo lib. Dovremmo poi mettere il plugin compilato nella directory plugins del genitore della directory corrente.

Registrare una classe in QML

 In dialogPlugin.h:

#include <QtDeclarative/QDeclarativeExtensionPlugin>

class DialogPlugin : public QDeclarativeExtensionPlugin
 {
 Q_OBJECT

public:
 void registerTypes(const char *uri);

};

La nostra classe plugin, DialogPlugin è una sottoclasse di QDeclarativeExtensionPlugin. Questa prevede che dobbiamo implementare la funzione ereditata, registerTypes(). Il file dialogPlugin.cpp assomiglia a questo:

 DialogPlugin.cpp:

#include "dialogPlugin.h"
 #include "directory.h"
 #include "file.h"
 #include <QtDeclarative/qdeclarative.h>

void DialogPlugin::registerTypes(const char '''uri){

 qmlRegisterType<Directory>(uri, 1, 0, "Directory");
 qmlRegisterType<File>(uri, 1, 0,"File");
 }

 Q_EXPORT_PLUGIN2(FileDialog, DialogPlugin);

p. La funzione registerTypes() registra le nostre classi File e Directory in QML. Questa funzione ha bisogno dell nome della classe per il suo template, un numero di versione principale, un numero di versione minore, e un nome per le nostre classi.

p. Abbiamo poi bisogno di esportare il plugin utilizzando la macro Q_EXPORT_PLUGIN2. Si noti che nel file dialogPlugin.h, abbiamo la macro Q_OBJECT in cima alla nostra classe. Inoltre, abbiamo bisogno di eseguire qmake sul file di progetto per generare il necessario codice meta-object.

Creare proprietà QML in una classe C++

p. Possiamo ora creare elementi e proprietà QML utilizzando C++ e il Qt Meta-Object System. Siamo in grado di implementare le proprietà utilizzando gli slot e le signal, rendendole note anche a Qt. Queste proprietà possono poi essere utilizzate direttamente in QML.

p. Per l'editor di testo, dobbiamo essere in grado di caricare e salvare file. Normalmente, queste funzionalità sono contenute in una finestra di dialogo. Per fortuna, possiamo usare QDir, QFile e QTextStream per implementare la lettura di directory e gli stream di input/output.

 class Directory : public QObject{

 Q_OBJECT

 Q_PROPERTY(int filesCount READ filesCount CONSTANT)
 Q_PROPERTY(QString filename READ filename WRITE setFilename NOTIFY filenameChanged)
 Q_PROPERTY(QString fileContent READ fileContent WRITE setFileContent NOTIFY fileContentChanged)
 Q_PROPERTY(QDeclarativeListProperty<File> files READ files CONSTANT )

 …

p. La classe Directory utilizza il Meta-Object System di Qt per registrare le proprietà di cui ha bisogno per realizzare la gestione dei file. La classe Directory è esportata come un plugin ed è utilizzabile in QML come l'elemento Directory. Ciascuna delle proprietà definite utilizzando la macro Q_PROPERTY è anche una proprietà QML.

p. La macro Q_PROPERTY dichiara al Meta-Object System di Qt sia la proprietà, che le sue funzioni di lettura e scrittura. Ad esempio, la proprietà filename, di tipo QString, è leggibile con la funzione filename() e scrivibile utilizzando la funzione setFilename(). Inoltre, vi è una signal associato alla proprietà filename chiamata filenameChanged(), che viene emesso ogni volta che la proprietà cambia. Le funzioni di lettura e scrittura sono dichiarate come public nel file header (.h).

p. Analogamente, abbiamo le altre proprietà dichiarate secondo il loro utilizzo. La proprietà filesCount indica il numero di file in una directory. La proprietà filename è impostata con il nome del file attualmente selezionato ed il contenuto del file salvato. o caricato, viene memorizzato nella proprietà fileContent.

 Q_PROPERTY(QDeclarativeListProperty<File> files READ files CONSTANT )

p. La lista di proprietà files è un elenco di tutti i file, filtrati, presenti in una directory. La classe Directory è implementato in modo da filtrare i file di testo non validi; solo i file con estensione .txt sono validi. Inoltre, una QList può essere utilizzata nei file QML dichiarandola come QDeclarativeListProperty in C+. L'oggetto deve ereditare da un QObject, quindi, la classe File deve anche ereditare da QObject. Nella classe Directory, l'elenco di oggetti di tipo File è memorizzato in una QList chiamata m_fileList.

 class File : public QObject{

 Q_OBJECT
 Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged)

 …
 };

p. Le proprietà possono quindi essere utilizzate direttamente in QML come parte integrante delle proprietà dell'elemento Directory. Si noti che non abbiamo dovuto creare un proprietà identificatore id nel nostro codice C.

 Directory{
 id: directory

 filesCount
 filename
 fileContent
 files

 files[0].name
 }

p. Poiché QML utilizza la sintassi e la struttura di Javascript, siamo in grado di iterare l'elenco dei file e recuperare le sue proprietà. Per recuperare la proprietà nome del primo file, possiamo usare

files[0].name<code>

p. Anche le normali funzioni C''+ sono accessibili da QML. Le funzioni di caricamento e di salvataggio dei file sono implementate in C++ e dichiarate utilizzando la macro [http://doc.qt.nokia.com/4.7/qobject.html#Q_INVOKABLE Q_INVOKABLE]. In alternativa, possiamo dichiarare le funzioni come uno ''slot'' e renderle in questo modo accessibili da QML.

In Directory.h:

Q_INVOKABLE void saveFile();
Q_INVOKABLE void loadFile();

p. La classe Directory deve anche notificare altri oggetti ogni volta che c'è un cambiamento nel contenuto della directory. Questa funzione viene eseguita utilizzando una ''signal''. Come accennato in precedenza, le ''signal'' QML hanno un gestore associato che ha lo stesso nome preceduto dal prefisso ''on''. La ''signal'' è denominato ''directoryChanged'' e viene emesso ogni volta che c'è un aggiornamento della directory. L'aggiornamento ricarica semplicemente il contenuto della directory e aggiorna l'elenco dei file validi della directory. Gli elementi QML possono poi essere notificati implementand il gestore di ''signal'' ''onDirectoryChanged''.

p. Le proprietà ''list'' ha bisogno di essere ulteriormente esplorata. Questo perché le proprietà di tipo ''list'' utilizzano delle funzioni di callback per accedere e modificare il contenuto dell'elenco. La proprietà ''list'' è di tipo ''QDeclarativeListProperty<File>'' . Ogni volta che si accede alla lista, la funzione di accesso (accessor) deve restituire una oggetto di tipo ''QDeclarativeListProperty<File>''. Il tipo del ''template'', ''File'', deve essere un derivato di QObject. Inoltre, per creare la [http://doc.qt.nokia.com/4.7/qdeclarativelistproperty.html QDeclarativeListProperty], le funzioni di accesso e di modifica (modifier) devono essere passati al costruttore della classe come puntatori a funzione. La lista, una ''QList'' nel nostro caso, deve anche essere una lista di puntatori a ''File''.

p.Il costruttore di [http://doc.qt.nokia.com/4.7/qdeclarativelistproperty.html QDeclarativeListProperty] e l'implementazione in ''Directory'':

QDeclarativeListProperty ( QObject object, void * data, AppendFunction append, CountFunction count = 0, AtFunction at = 0, ClearFunction clear = 0 )
QDeclarativeListProperty<File>( this, &m_fileList, &appendFiles, &filesSize, &fileAt, &clearFilesPtr );

Il costruttore passa i puntatori alle funzioni che implementano rispettivamente: aggiungi alla lista, enumera la lista, recupera l'oggetto utilizzando un indice, e svuota la lista. Solo la funzione ''append'' è obbligatoria. Si noti che i puntatori a funzione devono corrispondere alla definizione di [http://doc.qt.nokia.com/4.7/qdeclarativelistproperty.html#AppendFunction-typedef AppendFunction], [http://doc.qt.nokia.com/4.7/qdeclarativelistproperty.html#CountFunction-typedef CountFunction], [http://doc.qt.nokia.com/4.7/qdeclarativelistproperty.html#AtFunction-typedef AtFunction], e [http://doc.qt.nokia.com/4.7/qdeclarativelistproperty.html#ClearFunction-typedef ClearFunction].

void appendFiles(QDeclarativeListProperty<File> * property, File * file)
File* fileAt(QDeclarativeListProperty<File> * property, int index)
int filesSize(QDeclarativeListProperty<File> * property)
void clearFilesPtr(QDeclarativeListProperty<File> *property)

Per semplificare la nostra finestra di dialogo file, la classe ''Directory'' filtra i file di testo non validi, che sono file che non hanno l'estensione .txt. Se un nome di file non ha l'estensione .txt, allora non sarà visibile nella nostra finestra di dialogo file. Inoltre, l'applicazione assicura che i file salvati abbiano l'estensione .txt nel nome del file. La classe ''Directory'' utilizza [http://doc.qt.nokia.com/4.7/qtextstream.html QTextStream] per leggere e scrivere il contenuto del file.

Tramite il nostro elemento ''Directory'', è possibile recuperare tutti i file come una lista, sapere quanti sono i file di tipo testo nella directory dell'applicazione, ottenere il nome del file corrente e il suo contenuto come stringa, ed essere informati quando ci sono cambiamenti nel contenuto delle directory.

Per costruire il plugin, bisogna eseguire ''qmake'' con il file di progetto ''cppPlugins.pro'', quindi lanciare ''make'' fare per compilare e trasferire il plugin nella directory ''plugins''.

== Importare un plugin in QML ==

Il programma ''qmlviewer'' importa i file che si trovano nella stessa directory dell'applicazione. Possiamo anche creare un file ''qmldir'' contenente la posizione dei file QML che vogliamo importare. Il file qmldir può anche memorizzare le posizioni di plugin e altre risorse.

In qmldir:

Button ./Button.qml

FileDialog ./FileDialog.qml
TextArea ./TextArea.qml
TextEditor ./TextEditor.qml
EditMenu ./EditMenu.qml

plugin FileDialog plugins

Il plugin che abbiamo appena creato si chiama FileDialog, come indicato dal campo ''TARGET'' nel file di progetto. Il plugin è compilato e copiato nella directory ''plugins''.

== Integrare una finestra di dialogo nel menu File ==

Il nostro ''FileMenu'' ha bisogno di visualizzare l'elemento ''FileDialog'', contenente un elenco dei file di testo in una directory consentendo così all'utente di selezionare un file facendo clic sulla lista. Abbiamo anche bisogno di collegare i pulsanti per salvare, caricare e creare nuovo, alle loro rispettive azioni. Il ''FileMenu'' contiene anche un campo di input di testo per consentire all'utente di digitare un nome di file utilizzando la tastiera.

L'elemento ''Directory'' viene utilizzato nel file ''FileMenu.qml'' e avvisa l'elemento ''FileDialog'' quando la directory ha aggiornato il suo contenuto. Questa notifica viene eseguita nel gestore del segnale, ''onDirectoryChanged''.

In FileMenu.qml:

Directory{

id:directory
filename: textInput.text
onDirectoryChanged: fileDialog.notifyRefresh()
}

Allineandola con la semplicità della nostra applicazione, la finestra di dialogo file è sempre visibile e non visualizza file di testo non validi, che non hanno una estensione .txt nei loro nomi.

In FileDialog.qml:

signal notifyRefresh()

onNotifyRefresh: dirView.model = directory.file

L'elemento ''FileDialog'' visualizza il contenuto di una directory leggendo la lista di proprietà chiamata ''files''. I file vengono utilizzati come modello di un elemento [http://doc.qt.nokia.com/4.7/qml-gridview.html GridView], che visualizza gli elementi dati in una griglia su indicazione di un componente delegato. Il delegato gestisce l'aspetto del modello e la nostra finestra di dialogo file utilizza semplicemente una griglia con il testo centrato nel mezzo. Cliccando sul nome del file compare un rettangolo per evidenziare il nome del file. Il ''FileDialog'' viene notificato ogni volta che la ''signal'' ''notifyRefresh'' viene emessa, ricaricando così i file nella directory.

In FileMenu.qml:

Button{

id: newButton
label: "New"
onButtonClick:{
textArea.textContent = ""
}
}
Button{
id: loadButton
label: "Load"
onButtonClick:{
directory.filename = textInput.text
directory.loadFile()
textArea.textContent = directory.fileContent
}
}
Button{
id: saveButton
label: "Save"
onButtonClick:{
directory.fileContent = textArea.textContent
directory.filename = textInput.text
directory.saveFile()
}
}
Button{
id: exitButton
label: "Exit"
onButtonClick:{
Qt.quit()
}
}

Il nostro FileMenu può adesso essere connesso alle rispettive azioni. Il pulsante saveButton trasferirà il testo dal TextEdit alla proprietà fileContent della directory, quindi copia il nome del file nel campo di input testo. Infine, il pulsante chiama la funzione savefile(), per salvare il contenuto del file. Il pulsante loadButton ha una comportamento simile. Inoltre, l'azione New svuota il contenuto del TextEdit.

Per finire, i pulsanti EditMenu sono collegate alle funzioni di TextEdit per copiare, incollare e selezionare tutto il testo nell'editor.

L'editor di testo completo