Definición de tipos de objeto mediante documentos QML

Una de las principales características de QML es que permite definir fácilmente tipos de objeto QML de forma ligera a través de documentos QML para adaptarse a las necesidades de las aplicaciones QML individuales. El módulo estándar Qt Quick proporciona varios tipos como Rectangle, Text y Image para crear una aplicación QML; además de éstos, puede definir fácilmente sus propios tipos QML para reutilizarlos en su aplicación. Esta capacidad de crear sus propios tipos constituye la base de cualquier aplicación QML.

Definición de un tipo de objeto con un archivo QML

Cómo nombrar tipos de objeto QML personalizados

Para crear un tipo de objeto, se debe colocar un documento QML en un archivo de texto denominado como <NombreTipo>.qml donde <NombreTipo> es el nombre deseado del tipo. El nombre del tipo tiene los siguientes requisitos

• Debe estar compuesto por caracteres alfanuméricos o guiones bajos.
• Debe comenzar con una letra mayúscula.

El motor reconocerá automáticamente este documento como definición de un tipo QML. Además, un tipo definido de esta forma se pone automáticamente a disposición de otros archivos QML dentro del mismo directorio local, ya que el motor busca dentro del directorio inmediato cuando resuelve nombres de tipos QML.

Definición personalizada de tipos QML

Por ejemplo, a continuación se muestra un documento que declara un Rectangle con un hijo MouseArea. El documento se ha guardado en un archivo denominado SquareButton.qml:

// SquareButton.qml
import QtQuick 2.0

Rectangle {
    property int side: 100
    width: side; height: side
    color: "red"

    MouseArea {
        anchors.fill: parent
        onClicked: console.log("Button clicked!")
    }
}

Como el archivo se llama SquareButton.qml, ahora puede ser utilizado como un tipo llamado SquareButton por cualquier otro archivo QML dentro del mismo directorio. Por ejemplo, si hubiera un archivo myapplication.qml en el mismo directorio, podría hacer referencia al tipo SquareButton:

// myapplication.qml
import QtQuick 2.0

SquareButton {}

Esto crea un Rectangle rojo de 100 x 100 con un MouseArea interior, como se define en SquareButton.qml. Cuando el motor carga este documento myapplication.qml, carga el documento SquareButton.qml como un componente y lo instancia para crear un objeto SquareButton.

El tipo SquareButton encapsula el árbol de objetos QML declarados en SquareButton.qml. Cuando el motor QML instancia un objeto SquareButton a partir de este tipo, está instanciando un objeto del árbol Rectangle declarado en SquareButton.qml.

Componentes en línea

A veces, puede resultar inconveniente crear un nuevo archivo para un tipo, por ejemplo, cuando se reutiliza un pequeño delegado en varias vistas. Si en realidad no necesita exponer el tipo, sino que sólo necesita crear una instancia, Component es una opción. Pero si quieres declarar propiedades con los tipos de componentes, o si quieres usarlo en múltiples archivos, Component no es una opción. En ese caso, puede utilizar componentes en línea. Los componentes en línea declaran un nuevo componente dentro de un archivo. La sintaxis es la siguiente

component <component name> : BaseType {
    // declare properties and bindings here
}

Dentro del archivo que declara el componente en línea, se puede hacer referencia al tipo simplemente por su nombre.

// Images.qml
import QtQuick

Item {
    component LabeledImage: Column {
        property alias source: image.source
        property alias caption: text.text

        Image {
            id: image
            width: 50
            height: 50
        }
        Text {
            id: text
            font.bold: true
        }
    }

    Row {
        LabeledImage {
            id: before
            source: "before.png"
            caption: "Before"
        }
        LabeledImage {
            id: after
            source: "after.png"
            caption: "After"
        }
    }
    property LabeledImage selectedImage: before
}

En otros archivos, debe ir precedido del nombre del componente que lo contiene.

// LabeledImageBox.qml
import QtQuick

Rectangle {
    property alias caption: image.caption
    property alias source: image.source
    border.width: 2
    border.color: "black"
    Images.LabeledImage {
        id: image
    }
}

// A.qml
import QtQuick

Item {
    id: root
    property string message: "From A"
    component MyInlineComponent : Item {
        Component.onCompleted: console.log(root.message)
    }
}
// B.qml
import QtQuick

Item {
    A.MyInlineComponent {}
}

Importación de tipos definidos fuera del directorio actual

Si SquareButton.qml no estuviera en el mismo directorio que myapplication.qml, el tipo SquareButton tendría que estar disponible específicamente a través de una sentencia import en myapplication.qml. Podría importarse desde una ruta relativa en el sistema de archivos, o como un módulo instalado; véase módulo para más detalles.

Atributos accesibles de los tipos personalizados

La definición de objeto raíz de un archivo .qml define los atributos disponibles para un tipo QML. Todas las propiedades, señales y métodos que pertenecen a este objeto raíz -ya sean declarados por el usuario o procedan del tipo QML del objeto raíz- son accesibles externamente y pueden leerse y modificarse para objetos de este tipo.

Por ejemplo, el tipo de objeto raíz en el archivo SquareButton.qml anterior es Rectangle. Esto significa que cualquier propiedad definida por el tipo Rectangle puede modificarse para un objeto SquareButton. El código siguiente define tres objetos SquareButton con valores personalizados para algunas de las propiedades del objeto raíz Rectangle del tipo SquareButton:

// application.qml
import QtQuick 2.0

Column {
    SquareButton { side: 50 }
    SquareButton { x: 50; color: "blue" }
    SquareButton { radius: 10 }
}

Los atributos a los que pueden acceder los objetos del tipo QML personalizado incluyen cualquier propiedad, método y señal personalizados que se hayan definido adicionalmente para un objeto. Por ejemplo, supongamos que el Rectangle de SquareButton.qml se hubiera definido como sigue, con propiedades, métodos y señales adicionales:

// SquareButton.qml
import QtQuick 2.0

Rectangle {
    id: root

    property bool pressed: mouseArea.pressed

    signal buttonClicked(real xPos, real yPos)

    function randomizeColor() {
        root.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1)
    }

    property int side: 100
    width: side; height: side
    color: "red"

    MouseArea {
        id: mouseArea
        anchors.fill: parent
        onClicked: (mouse)=> root.buttonClicked(mouse.x, mouse.y)
    }
}

Cualquier objeto SquareButton podría hacer uso de la propiedad pressed, la señal buttonClicked y el método randomizeColor() que se han añadido a la raíz Rectangle:

// application.qml
import QtQuick 2.0

SquareButton {
    id: squareButton

    onButtonClicked: (xPos, yPos)=> {
        console.log("Clicked", xPos, yPos)
        randomizeColor()
    }

    Text { text: squareButton.pressed ? "Down" : "Up" }
}

Tenga en cuenta que cualquiera de los valores id definidos en SquareButton.qml no son accesibles para los objetos SquareButton, ya que los valores id sólo son accesibles desde el ámbito del componente en el que se declara un componente. La definición de objeto SquareButton anterior no puede referirse a mouseArea para referirse al hijo MouseArea, y si tuviera un id de root en lugar de squareButton, esto no entraría en conflicto con el id del mismo valor para el objeto raíz definido en SquareButton.qml ya que los dos se declararían dentro de ámbitos separados.