Archivos qmldir de definición de módulos

Existen dos tipos distintos de archivos qmldir:

• Archivos de listado de directorios de documentos QML
• Archivos de definición de módulos QML

Esta documentación sólo cubre la segunda forma de archivo qmldir, que enumera los tipos QML, archivos JavaScript y plugins disponibles en un módulo. Para obtener más información sobre la primera forma del archivo qmldir, consulte el listado de directorios qmldir.

Contenido de un archivo qmldir de definición de módulo

Un archivo qmldir es un archivo de texto plano que contiene los siguientes comandos:

• Declaración de identificador de módulo
• Declaración de tipo de objeto
• Declaración de tipo de objeto interno
• Declaración de recursos JavaScript
• Declaración de plugin
• Declaración de Plugin Classname
• Descripción del tipo de archivo Declaración
• Declaración de Dependencias de Módulos
• Declaración de importación de módulos
• Declaración de soporte de diseñador
• Declaración de ruta preferida

Además de comandos, también puede añadir comentarios, que son líneas que empiezan por #.

Declaración de identificador de módulo

module <ModuleIdentifier>

Declara el identificador del módulo. El <ModuleIdentifier> es el identificador (notación URI punteada) del módulo, que debe coincidir con la ruta de instalación del módulo.

La directiva del identificador del módulo debe ser la primera línea del archivo. Sólo puede haber una directiva de identificador de módulo en el archivo qmldir.

Ejemplo:

module ExampleModule

Declaración de tipo de objeto

[singleton] <TypeName> <InitialVersion> <File>

Declara un tipo de objeto QML que el módulo pondrá a disposición.

• [singleton] Opcional. Se utiliza para declarar un tipo singleton.
• <TypeName> es el tipo que se pone a disposición
• <InitialVersion> es la versión del módulo para la que debe estar disponible el tipo
• <File> es el nombre (relativo) del archivo QML que define el tipo

En el archivo qmldir pueden existir cero o más declaraciones de tipo de objeto. Sin embargo, cada tipo de objeto debe tener un nombre de tipo único dentro de cualquier versión particular del módulo.

Ejemplo:

//Style.qml with custom singleton type definition
pragma Singleton
import QtQuick 2.0

QtObject {
    property int textSize: 20
    property color textColor: "green"
}

// qmldir declaring the singleton type
module CustomStyles
singleton Style 1.0 Style.qml

// singleton type in use
import QtQuick 2.0
import CustomStyles 1.0

Text {
    font.pixelSize: Style.textSize
    color: Style.textColor
    text: "Hello World"
}

Declaración de tipo de objeto interno

internal <TypeName> <File>

Declara un tipo de objeto que se encuentra en el módulo pero que no debe ponerse a disposición de los usuarios del módulo.

Pueden existir cero o más declaraciones de tipo de objeto interno en el archivo qmldir.

Ejemplo:

internal MyPrivateType MyPrivateType.qml

Esto es necesario si el módulo se importa de forma remota (consulte Módulos identificados instalados de forma remota) porque si un tipo exportado depende de un tipo no exportado dentro del módulo, el motor también debe cargar el tipo no exportado.

Declaración de recursos JavaScript

<ResourceIdentifier> <InitialVersion> <File>

Declara un archivo JavaScript que el módulo pondrá a disposición. El recurso estará disponible a través del identificador especificado con el número de versión especificado.

Pueden existir cero o más declaraciones de recursos JavaScript en el archivo qmldir. Sin embargo, cada recurso JavaScript debe tener un identificador único dentro de cualquier versión particular del módulo.

Ejemplo:

MyScript 1.0 MyScript.js

Consulte la documentación sobre la definición de recursos JavaScript y la importación de recursos JavaScript en QML para obtener más información.

Declaración de plugin

[optional] plugin <Name> [<Path>]

Declara un complemento que el módulo pondrá a disposición.

• optional denota que el plugin en sí no contiene ningún código relevante y sólo sirve para cargar una biblioteca a la que enlaza. Si se da, y si ya hay disponibles tipos para el módulo, indicando que la biblioteca se ha cargado por algún otro medio, QML no cargará el plugin.
• <Name> es el nombre de la biblioteca del complemento. No suele coincidir con el nombre del archivo binario del complemento, que depende de la plataforma. Por ejemplo, la biblioteca MyAppTypes produciría libMyAppTypes.so en Linux y MyAppTypes.dll en Windows.
• <Path> (opcional) especifica
  • una ruta absoluta al directorio que contiene el archivo del complemento, o bien
  • una ruta relativa desde el directorio que contiene el archivo qmldir hasta el directorio que contiene el archivo del complemento.

Por defecto, el motor busca la biblioteca de plugins en el directorio que contiene el archivo qmldir. (La ruta de búsqueda de plugins puede consultarse con QQmlEngine::pluginPathList() y modificarse con QQmlEngine::addPluginPath().)

Pueden existir cero o más declaraciones de plugins C++ en el archivo qmldir. Sin embargo, dado que la carga de plugins es una operación relativamente costosa, se recomienda a los clientes que especifiquen como máximo un único plugin.

Ejemplo:

plugin MyPluginLibrary

Declaración de nombre de clase de complemento

classname <C++ plugin class>

Proporciona el nombre de clase del plugin C++ utilizado por el módulo.

Esta información es necesaria para todos los módulos QML que dependen de un plugin C++ para una funcionalidad adicional. Qt Quick las aplicaciones creadas con enlace estático no pueden resolver las importaciones de módulos sin esta información.

Declaración de archivo de descripción de tipos

typeinfo <File>

Declara un archivo de descripción de tipos para el módulo que puede ser leído por herramientas QML como Qt Creator para acceder a la información sobre los tipos definidos por los plugins del módulo. <File> es el nombre (relativo) de un archivo .qmltypes.

Ejemplo:

typeinfo mymodule.qmltypes

Sin un archivo de este tipo, es posible que las herramientas QML no puedan ofrecer funciones como la finalización de código para los tipos definidos en sus plugins.

Declaración de dependencias del módulo

depends <ModuleIdentifier> <InitialVersion>

Declara que este módulo depende de otro.

Ejemplo:

depends MyOtherModule 1.0

Esta declaración sólo es necesaria en los casos en que la dependencia está oculta: por ejemplo, cuando el código C++ de un módulo se utiliza para cargar QML (quizás condicionalmente), que a su vez depende de otros módulos. En tales casos, la declaración depends es necesaria para incluir los otros módulos en los paquetes de la aplicación.

Declaración de importación de módulo

import <ModuleIdentifier> [<Version>]

Declara que este módulo importa otro.

Ejemplo:

import MyOtherModule 1.0

Los tipos del otro módulo están disponibles en el mismo espacio de nombres de tipos en el que se importa este módulo. Omitiendo la versión se importa la última versión disponible del otro módulo. Especificando auto como versión importa la misma versión que la versión de este módulo especificada en la declaración QML import.

Declaración de soporte del diseñador

designersupported

Establezca esta propiedad si el plugin es compatible con Qt Quick Designer. Por defecto, el plugin no será soportado.

Un complemento compatible con Qt Quick Designer debe probarse correctamente. Esto significa que el plugin no se bloquea cuando se ejecuta dentro del qml2puppet que es utilizado por Qt Quick Designer para ejecutar QML. Generalmente, el plugin debe funcionar bien en Qt Quick Designer y no causar ningún problema, como ocupar cantidades excesivas de memoria, ralentizar mucho el qml2puppet, o cualquier otra cosa que haga que el plugin sea inutilizable en Qt Quick Designer.

Los elementos de un plugin no compatible no se pintan en el Diseñador de Qt Quick, pero siguen estando disponibles como cuadros vacíos y sus propiedades pueden editarse.

Declaración de ruta preferida

prefer <Path>

Esta propiedad indica al motor QML que cargue cualquier otro archivo de este módulo desde <ruta>, en lugar de hacerlo desde el directorio actual. Puede utilizarse para cargar archivos compilados con qmlcachegen.

Por ejemplo, puede añadir los archivos QML de un módulo como recursos a una ruta de recursos :/my/path/MyModule/. A continuación, añada prefer :/my/path/MyModule al archivo qmldir para utilizar los archivos del sistema de recursos, en lugar de los del sistema de archivos. Si luego utilizas qmlcachegen para ellos, los archivos precompilados estarán disponibles para cualquier cliente del módulo.

Semántica de versiones

Todos los tipos QML que se exportan para una determinada versión principal están disponibles con la última versión de la misma versión principal. Por ejemplo, si un módulo proporciona un tipo MyButton en la versión 1.0 y un tipo MyWindow en la versión 1.1, los clientes que importen la versión 1.1 del módulo podrán utilizar los tipos MyButton y MyWindow. Sin embargo, no ocurre lo mismo a la inversa: un tipo exportado para una versión menor concreta no puede utilizarse importando una versión menor anterior o más antigua. En el ejemplo mencionado anteriormente, si el cliente hubiera importado la versión 1.0 del módulo, sólo podría utilizar el tipo MyButton pero no el tipo MyWindow.

Un módulo puede ofrecer varias versiones principales, pero los clientes sólo tienen acceso a una versión principal cada vez. Por ejemplo, la importación de MyExampleModule 2.0 proporciona acceso sólo a esa versión principal y no a la versión principal anterior. Aunque puede organizar los artefactos que pertenecen a diferentes versiones principales en un directorio sigle y un archivo qmldir, se recomienda utilizar directorios diferentes para cada versión principal. Si opta por el enfoque anterior (un directorio y un archivo qmldir ), intente utilizar el sufijo de la versión para los nombres de los archivos. Por ejemplo, los artefactos que pertenecen a MyExampleModule 2.0 pueden utilizar el sufijo .2 en su nombre de archivo.

No se puede importar una versión si no se han exportado explícitamente tipos para esa versión. Si un módulo proporciona un tipo MyButton en la versión 1.0 y un tipo MyWindow en la versión 1.1, no podrá importar la versión 1.2 o la versión 2.0 de ese módulo.

Un tipo puede ser definido por diferentes archivos en diferentes versiones menores. En este caso, se utiliza la versión más parecida cuando la importan los clientes. Por ejemplo, si un módulo hubiera especificado los siguientes tipos a través de su archivo qmldir:

module ExampleModule
MyButton 1.0 MyButton.qml
MyButton 1.1 MyButton11.qml
MyButton 1.3 MyButton13.qml
MyRectangle 1.2 MyRectangle12.qml

un cliente que importe la versión 1.2 de ExampleModule puede utilizar la definición de tipo MyButton proporcionada por MyButton11.qml, ya que es la última versión de ese tipo, y la definición de tipo MyRectangle proporcionada por MyRectangle12.qml.

El sistema de versiones garantiza que un archivo QML determinado funcione independientemente de la versión del software instalado, ya que una importación versionada sólo importa tipos para esa versión, dejando disponibles otros identificadores, aunque la versión instalada real pudiera proporcionar esos identificadores.

Ejemplo de archivo qmldir

A continuación se muestra un ejemplo de archivo qmldir:

module ExampleModule
CustomButton 2.0 CustomButton20.qml
CustomButton 2.1 CustomButton21.qml
plugin examplemodule
MathFunctions 2.0 mathfuncs.js

El archivo qmldir anterior define un módulo denominado "ExampleModule". Define el tipo de objeto CustomButton QML en las versiones 2.0 y 2.1 del módulo, con diferentes implementaciones para cada versión. Especifica un plugin que debe ser cargado por el motor cuando el módulo es importado por los clientes, y ese plugin puede registrar varios tipos definidos por C++ con el sistema de tipos QML. En sistemas tipo Unix, el motor QML intenta cargar libexamplemodule.so como QQmlExtensionPlugin, y en Windows carga examplemodule.dll como QQmlExtensionPlugin. Por último, el archivo qmldir especifica un recurso JavaScript, que sólo está disponible si se importa la versión 2.0 o una posterior (bajo la misma versión principal) del módulo.

Si el módulo se instala en la ruta de importación de QML, los clientes podrían importar y utilizar el módulo de la siguiente manera:

import QtQuick 2.0
import ExampleModule 2.1

Rectangle {
    width: 400
    height: 400
    color: "lightsteelblue"

    CustomButton {
        color: "gray"
        text: "Click Me!"
        onClicked: MathFunctions.generateRandom() > 10 ? color = "red" : color = "gray";
    }
}

El tipo CustomButton utilizado anteriormente provendría de la definición especificada en el archivo CustomButton21.qml, y el recurso JavaScript identificado por el identificador MathFunctions se definiría en el archivo mathfuncs.js.

Archivos de descripción de tipos

Los módulos QML pueden hacer referencia a uno o varios archivos de información de tipos en su archivo qmldir. Éstos suelen tener la extensión .qmltypes y son leídos por herramientas externas para obtener información sobre tipos definidos en C++ y normalmente importados a través de plugins.

Como tales, los archivos qmltypes no afectan a la funcionalidad de un módulo QML. Su único uso es permitir que herramientas como Qt Creator proporcionen finalización de código, comprobación de errores y otras funciones a los usuarios de su módulo.

Cualquier módulo que defina tipos QML en C++ también debe enviar un archivo de descripción de tipos.

La mejor manera de crear un archivo qmltypes para su módulo es generarlo utilizando el sistema de construcción y las macros QML_ELEMENT. Si sigues la documentación al respecto, no necesitarás hacer nada más. qmltyperegistrar generará automáticamente los archivos .qmltypes.

Ejemplo: Si tu módulo está en /tmp/imports/My/Module, se generará un archivo llamado plugins.qmltypes junto con el binario del plugin.

Añade la línea

typeinfo plugins.qmltypes

a /tmp/imports/My/Module/qmldir para registrarlo.