QML Hello World Tutorial/es

Tutorial "Hola Mundo" con QML

Este tutorial provee una introducción a QML, el lenguage de marcado de Qt Quick. Este tutorial no cubre todo; sólo hace énfasis en enseñar principios clave, las funciones se presentan tan pronto sea necesario.

A través de los distintos pasos de este tutorial aprenderemos acerca de los tipos básicos de QML, crearemos nuestros propios componentes QML con propiedades y signals, y crearemos una animación simpmle con la ayuda de estados y transicionnes.

El capítulo uno comienza con un programa mínimo de "Hola mundo" y en los siguientes capítulos presentaremos nuevos conceptos.

El código fuente del tutorial está ubicado en el directorio $QTDIR/examples/declarative/tutorials/helloworld.

Capítulos del tutorial:
# Tipos Básicos
# Componentes QML
# Estados y Transiciones

Tipos Básicos

El primer programa con QML es un simple "Hola mundo" que introduce algunos conceptos básicos de QML. La imagen de abajo muestra una captura de pantalla de este programa.

El código QML para esta aplicación es el siguiente:

 import Qt 4.7

Rectangle {<br /> id: page<br /> width: 500; height: 200<br /> color: &quot;lightgray&amp;quot;

Text {<br /> id: helloText<br /> text: &quot;Hello world!&quot;<br /> y: 30<br /> anchors.horizontalCenter: page.horizontalCenter<br /> font.pointSize: 24; font.bold: true<br /> }<br /> }

Importar

Primero importamos los tipos necesarios para este ejemplo. Muchos archivos QML importarán los tipos básicos de QML (como "Rectangle":http://doc.qt.nokia.com/4.7/qml-rectangle.html o "Image":http://doc.qt.nokia.com/4.7/qml-image.html) utilizando:

import Qt 4.7<code>

=== Elemento Rectangle ===

Rectangle {
id: page
width: 500; height: 200
color: "lightgray"

Declaramos nuestro elemento raíz el cuál será de tipo &quot;Rectangle&amp;quot;:http://doc.qt.nokia.com/4.7/qml-rectangle.html (Rectángulo), uno de los tipos básicos de QML. Le asignamos un id con el cuál podremos referirnos a él posteriormente, en este caso le llamaremos page (página). También establecemos sus propiedades de ancho, alto y color mediante las palabras clave width, height y color.<br />El elemento &quot;Rectangle&amp;quot;:http://doc.qt.nokia.com/4.7/qml-rectangle.html tiene muchas otras propiedades (como posición en X y en Y) pero por ahora dejaremos que conserven sus valores por defecto.

=== Elemento Text ===

Definimos un elemento tipo &quot;Text&amp;quot;:http://doc.qt.nokia.com/4.7/qml-text.html (Texto), el cuál será hijo del elemento Rectangle raiz y que mostrará el texto &quot;Hello world!&quot; La propiedad Y es utilizada para posicionar el texto de manera vertical a 30 pixeles por debajo de la parte superior de su padre.<br />Las propiedades font.pointSize (Tamaño de fuente) y font.bold (Negritas) están relacionadas con el tipo Font y es por ello que usan una notación con puntos (Tipo.propiedad).<br />La propiedad anchors.horizontalCenter (anclas.CentroHorizontal) se refiere al centro horizontal de un elemento. En este caso, especificamos que nuestro elemento helloText debe estar centrado horizontalmente en el elemento page. Consulte &quot;Anchor-based Layout&amp;quot;:http://doc.qt.nokia.com/4.7/qml-anchor-layout.html#anchor-layout (Organización basada en anclas)<br />Las propiedades font.pointSize y font.bold properties están realacionadas con la fuente y utilizan la &quot;notación de punto&amp;quot;:http://doc.qt.nokia.com/4.7/qdeclarativeintroduction.html#dot-properties.

=== Viendo el ejemplo ===

Para ver el ejemplo, ejecuta la herramienta &quot;QML Viewer&amp;quot;:http://doc.qt.nokia.com/4.7/qmlviewer.html(localizada en el directorio bin) con el nombre del archivo como primer argumento. Por ejemplo, para ejecutar el ejemplo desde la localización de la instalación, debes escribir:

bin/qml $QTDIR/examples/declarative/tutorials/helloworld/tutorial.qml

Componentes QML

Ahora agregaremos un selector de color a nuestra aplicación que servirá para cambiar el color de nuestro texto. La aplicación de esta sección del ejemplo se verá como en la siguiente imagen.

El selector de color está hecho de seis celdas de distintos colores. Para evitar escribir el código varias veces, primero creamos un nuevo componente llamaco Cell (Celda/Casilla). Los componentes proveen maneras de definir un nuevo tipo que puede ser reutilizado en otros archivos QML. Un componente de QML es como una caja negra que interactua con el mundo exterior a través de propiedades, señales y slots y que generalmente está definido en su propio archivo QML (Para más detalles puedes ver Defining new Components (Definiendo nuevos componentes))
El nombre del componente siempre debe comenzar con una letra mayúscula.

El código del componente Cell (Cell.qml) es el siguiente:

 import Qt 4.7

Item {<br /> id: container<br /> property alias cellColor: rectangle.color<br /> signal clicked(color cellColor)

width: 40; height: 25

Rectangle {<br /> id: rectangle<br /> border.color: &quot;white&amp;quot;<br /> anchors.fill: parent<br /> }

MouseArea {<br /> anchors.fill: parent<br /> onClicked: container.clicked(container.cellColor)<br /> }<br /> }

El componente Cell (Celda)

<br />Item {<br /> id: container<br /> property alias cellColor: rectangle.color<br /> signal clicked(color cellColor)

width: 40; height: 25

El elemento raíz de nuestro componente será de tipo "Item":http://doc.qt.nokia.com/4.7/qml-item.html (Elemento) y su id será container. El tipo Item es el elemento más básico de QML y es frecuentemente utilizado como contenedor para otros elementos.

 property alias cellColor: rectangle.color<code>

Declaramos una propiedad llamada cellColor. Está propiedad será accesible desde fuera del componente y por lo tanto nos permitirá instanciar celdas de distintos colores. Esta propiedas es sólo un alias de una propiedad existente: El color del rectángulo que compone la celda. (Par más información puedes ver &quot;Agregar Nuevas Propiedades&amp;quot;:http://doc.qt.nokia.com/4.7/qml-extending-types.html#adding-new-properties).

signal clicked(color cellColor)

Definimos una señal de nombre clicked (presionado) para nuestro componente y que tendrá un parámetro de tipo color, llamado color. Usaremos esta señal para cambiar el color del texto desde nuestro archivo main.

Rectangle {<br /> id: rectangle<br /> border.color: &quot;white&amp;quot;<br /> anchors.fill: parent<br />}

Definimos un elemento rectángulo que será hijo de nuestro elemento container y definimos sus propiedades.

MouseArea {<br /> anchors.fill: parent<br /> onClicked: container.clicked(container.cellColor)<br />}

Nuestro elemento Cell es básicamente un rectángulo de color igual a rectangle.id
La propiedad anchors.fill es una manera conveniente de establecer el tamaño de un elemento. En este caso el elemento rectangle tendrá el mismo tamaño que su padre. (consulte "Layout basado en anclas":http://doc.qt.nokia.com/4.7/qml-anchor-layout.html#anchor-layout)

MouseArea {<br /> anchors.fill: parent<br /> onClicked: container.clicked(container.cellColor)<br />}

Con el fin de cambiar el color del texto cuando presionemos una celda, creamos un elemento "MouseArea":http://doc.qt.nokia.com/4.7/qml-mousearea.html (Área de Mouse/Ratón) que tendrá el mismo tamaño que su padre.

El "MouseArea":http://doc.qt.nokia.com/4.7/qml-mousearea.html define una señal clicked esta señal se emita, queremos emitir nuestra propia señal clicked con el color del container como parámetro.

El archivo main de QML

En nuestro archivo de QML, usaremos nuestro componente Cell para crear el selector de color:

 import Qt 4.7

Rectangle {<br /> id: page<br /> width: 500; height: 200<br /> color: &quot;lightgray&amp;quot;

Text {<br /> id: helloText<br /> text: &quot;Hello world!&quot;<br /> y: 30<br /> anchors.horizontalCenter: page.horizontalCenter<br /> font.pointSize: 24; font.bold: true<br /> }

Grid {<br /> id: colorPicker<br /> x: 4; anchors.bottom: page.bottom; anchors.bottomMargin: 4<br /> rows: 2; columns: 3; spacing: 3

Cell { cellColor: &quot;red&amp;quot;; onClicked: helloText.color = cellColor }<br /> Cell { cellColor: &quot;green&amp;quot;; onClicked: helloText.color = cellColor }<br /> Cell { cellColor: &quot;blue&amp;quot;; onClicked: helloText.color = cellColor }<br /> Cell { cellColor: &quot;yellow&amp;quot;; onClicked: helloText.color = cellColor }<br /> Cell { cellColor: &quot;steelblue&amp;quot;; onClicked: helloText.color = cellColor }<br /> Cell { cellColor: &quot;black&amp;quot;; onClicked: helloText.color = cellColor }<br /> }<br /> }

Creamos nuestro selector de color colocando 6 Cells de distinto color en un elemento Grid (tabla/rejllla).

 Cell { cellColor: &quot;red&amp;quot;; onClicked: helloText.color = cellColor }<code>

Cuando la señal clicked de alguna Cell se disparé, estableceremos el color del texto que pasamos como parámetro al color del rectángulo que emite la señal.<br />Podemos reaccionar ante la emisión de cualquier señal de nuestros componentes a través de la propiedad &quot;onNombreDeSeñal&amp;quot;.

== Estados y Transiciones ==

Ahora haremos este ejemplo un poco más dinámico mediante states (estados) y transitions (transiciones). Haremos que nuestro texto se mueva hacia abajo, gire 180 grados y cambie su color a rojo al ser presionado.

La aplicación final se verá como en la siguiente imagen.

[[Image:http://doc.qt.nokia.com/4.7/images/declarative-tutorial3_animation.gif|http://doc.qt.nokia.com/4.7/images/declarative-tutorial3_animation.gif]]

Para ello es necesario cambiar el código de main.qml que quedará de la siguiente forma:

import Qt 4.7

Rectangle {
id: page
width: 500; height: 200
color: "lightgray"

Text {
id: helloText
text: "Hello world!"
y: 30
anchors.horizontalCenter: page.horizontalCenter
font.pointSize: 24; font.bold: true

MouseArea { id: mouseArea; anchors.fill: parent }

states: State {
name: "down"; when: mouseArea.pressed == true
PropertyChanges { target: helloText; y: 160; rotation: 180; color: "red" }
}

transitions: Transition {
from: ""; to: "down"; reversible: true
ParallelAnimation {
NumberAnimation { properties: "y,rotation"; duration: 500; easing.type: Easing.InOutQuad }
ColorAnimation { duration: 500 }
}
}
}

Grid {
id: colorPicker
x: 4; anchors.bottom: page.bottom; anchors.bottomMargin: 4
rows: 2; columns: 3; spacing: 3

Cell { cellColor: "red"; onClicked: helloText.color = cellColor }
Cell { cellColor: "green"; onClicked: helloText.color = cellColor }
Cell { cellColor: "blue"; onClicked: helloText.color = cellColor }
Cell { cellColor: "yellow"; onClicked: helloText.color = cellColor }
Cell { cellColor: "steelblue"; onClicked: helloText.color = cellColor }
Cell { cellColor: "black"; onClicked: helloText.color = cellColor }
}
}

En la línea 17 creamos un nuevo estado llamado down (presionado) para nuestro elemento texto. Este evento será activado cuándo la MouseArea esté presionada y desactivado cuando se deje de presionar.
El estado down incluye un conjunto de cambios a las propiedades de nuestro estado por defecto definido implicitamente (es decir, como fue inicialmente definido). Especificamente, establecemos la propiedad y de text a 160, su rotación a 180 y el color a rojo.

Ya que no queremos que los cambios de propiedades cambien inmediatamente sino que lo hagan lentamente a través de una animación, definimos una transición entre nuestros dos estados (línea 22). from y to definen los estados inicial y final de la transición. En este caso queremos que la transición ocurra del estado por defecto al estado down.

Debido a que queremos que la misma transición se ejecute en reversa al regresar del estado down al estado por defecto, establecemos la propiedad reversible a true (verdadero). Esto es equivalente a escribir dos transiciones por separado, una para cada estado como origen y destino.

El elemento ParallelAnimation (Animación paralela) se asegura que los dos tipos de animación (propiedades numéricas y el color) comiencen al mismo tiempo. También es posible que cambien una después de la otra utilizando el elemento SequentialAnimation (Animación secuencial).