Atributos de los objetos QML
Cada tipo de objeto QML tiene un conjunto definido de atributos. Cada instancia de un tipo de objeto se crea con el conjunto de atributos que se han definido para ese tipo de objeto. Existen varios tipos diferentes de atributos que se pueden especificar, los cuales se describen a continuación.
Atributos en las declaraciones de objetos
Una declaración de objeto en un documento QML define un nuevo tipo. También declara una jerarquía de objetos que se instanciará en caso de que se cree una instancia de ese tipo recién definido.
El conjunto de tipos de atributos de los tipos de objeto QML es el siguiente:
- el atributo «id»
- los atributos de propiedad
- atributos de señal
- atributos de controlador de señal
- atributos de método
- propiedades asociadas y atributos de controladores de señales asociados
- atributos de enumeración
Estos atributos se describen en detalle a continuación.
El atributo «id »
Un elemento QML puede tener como máximo un atributo «id ». Este atributo lo proporciona el propio lenguaje y no puede ser redefinido ni sobrescrito por ningún tipo de objeto QML.
Se puede asignar un valor al atributo id de una instancia de objeto para permitir que otros objetos identifiquen y hagan referencia a dicho objeto. Este « id » debe comenzar con una letra minúscula o un guión bajo, y no puede contener caracteres distintos de letras, números y guiones bajos. Tampoco puede ser una palabra clave de JavaScript. Consulta la especificación del lenguaje ECMAScript para ver una lista de dichas palabras clave.
Si utilizas en QML un nombre que no sea adecuado como identificador de JavaScript, como por ejemplo «as», no podrás hacer referencia al objeto identificado en JavaScript, lo que hace que el identificador resulte prácticamente inútil. No obstante, puedes seguir utilizando « QQmlContext » desde C++ para interactuar con dichos identificadores.
A continuación se muestran un objeto « TextInput » y un objeto « Text ». El valor de la propiedad « id » del objeto « TextInput » está establecido en «myTextInput». El objeto « Text » establece su propiedad « text » para que tenga el mismo valor que la propiedad « text » del objeto « TextInput », haciendo referencia a « myTextInput.text ». Ahora, ambos elementos mostrarán el mismo texto:
import QtQuick
Column {
width: 200; height: 200
TextInput { id: myTextInput; text: "Hello World" }
Text { text: myTextInput.text }
}Se puede hacer referencia a un objeto mediante su id desde cualquier punto del contexto QML en el que se haya creado. Por lo tanto, un valor id debe ser siempre único dentro de su contexto. Consulta «Ámbito y resolución de nombres» para obtener más información.
El contexto también está expuesto a C++ a través de la jerarquía QQmlContext. Por ejemplo, puedes recuperar el contexto de un objeto específico mediante la función qmlContext y solicitar otros objetos del mismo contexto:
QObject *textInput = qmlContext(theColumn)->objectForName("myTextInput");Una vez creada una instancia de objeto, el valor de su atributo `id` no se puede modificar. Aunque pueda parecer una propiedad ordinaria, el atributo ` id ` no es un atributo ` property ` habitual, y se le aplican semánticas especiales; por ejemplo, no es posible acceder a ` myTextInput.id ` en el ejemplo anterior.
Atributos de las propiedades
Una propiedad es un atributo de un objeto al que se le puede asignar un valor estático o vincularlo a una expresión dinámica. El valor de una propiedad puede ser leído por otros objetos. Por lo general, también puede ser modificado por otro objeto, a menos que un tipo concreto de QML lo haya prohibido explícitamente para una propiedad específica.
Definición de atributos de propiedad
Una propiedad puede definirse para un tipo en C++ registrando un ` Q_PROPERTY ` de una clase, que a continuación se registra en el sistema de tipos de QML. Alternativamente, una propiedad personalizada de un tipo de objeto puede definirse en una declaración de objeto en un documento QML con la siguiente sintaxis:
[default] [virtual] [override] [final] [required] [readonly] property <propertyType> <propertyName>De este modo, una declaración de objeto puede exponer un valor concreto a objetos externos o mantener un estado interno con mayor facilidad.
Los nombres de las propiedades deben comenzar con una letra minúscula y solo pueden contener letras, números y guiones bajos. Las palabras reservadas de JavaScript no son nombres válidos para propiedades. Las palabras clave default, required, readonly, virtual, override y final son opcionales y modifican la semántica de la propiedad que se está declarando. Consulta las siguientes secciones sobre propiedades por defecto, propiedades obligatorias, propiedades de solo lectura y semántica de anulación para obtener más información sobre su significado respectivo.
Al declarar una propiedad personalizada se crea implícitamente una señal de cambio de valor para dicha propiedad, así como un controlador de señales asociado denominado on<PropertyName>Changed, donde <PropertyName> es el nombre de la propiedad, con la primera letra en mayúscula.
Por ejemplo, la siguiente declaración de objeto define un nuevo tipo que deriva del tipo base Rectangle. Tiene dos nuevas propiedades, con un controlador de señal implementado para una de esas nuevas propiedades:
Rectangle {
property color previousColor
property color nextColor
onNextColorChanged: console.log("The next color will be: " + nextColor.toString())
}Tipos válidos en las definiciones de propiedades personalizadas
Cualquiera de los tipos de valor de QML puede utilizarse como tipo de propiedad personalizada. Por ejemplo, todas estas son declaraciones de propiedad válidas:
(Los valores de enumeración son simplemente números enteros y se puede hacer referencia a ellos utilizando el tipo « int » en su lugar).
Algunos tipos de valor los proporciona el módulo « QtQuick » y, por lo tanto, no pueden utilizarse como tipos de propiedad a menos que se importe dicho módulo. Consulta la documentación sobre tipos de valor de QML para obtener más detalles.
Tenga en cuenta que el tipo de valor ` var ` es un tipo marcador de posición genérico que puede contener cualquier tipo de valor, incluidas listas y objetos:
property var someNumber: 1.5
property var someString: "abc"
property var someBool: true
property var someList: [1, 2, "three", "four"]
property var someObject: Rectangle { width: 100; height: 100; color: "red" }Además, cualquier tipo de objeto QML puede utilizarse como tipo de propiedad. Por ejemplo:
property Item someItem
property Rectangle someRectangleEsto se aplica también a los tipos QML personalizados. Si se definiera un tipo QML en un archivo llamado ColorfulButton.qml (en un directorio que luego fuera importado por el cliente), entonces una propiedad de tipo ColorfulButton también sería válida.
Asignación de valores a los atributos de las propiedades
El valor de una propiedad de una instancia de objeto puede especificarse de dos formas distintas:
- una asignación de valor en la inicialización
- una asignación de valor imperativa
En ambos casos, el valor puede ser un valor estático o el resultado de una expresión de enlace.
Asignación de valor en la inicialización
La sintaxis para asignar un valor a una propiedad durante la inicialización es:
<propertyName> : <value>Si se desea, una asignación de valor de inicialización puede combinarse con una definición de propiedad en una declaración de objeto. En ese caso, la sintaxis de la definición de propiedad queda así:
[default] property <propertyType> <propertyName> : <value>A continuación se muestra un ejemplo de inicialización del valor de una propiedad:
import QtQuick
Rectangle {
color: "red"
property color nextColor: "blue" // combined property declaration and initialization
}Asignación de valor imperativa
Una asignación de valor imperativa es aquella en la que se asigna un valor de propiedad (ya sea un valor estático o una expresión de enlace) a una propiedad desde código JavaScript imperativo. La sintaxis de una asignación de valor imperativa es simplemente el operador de asignación de JavaScript, tal y como se muestra a continuación:
[<objectId>.]<propertyName> = valueA continuación se muestra un ejemplo de asignación de valor imperativa:
import QtQuick
Rectangle {
id: rect
Component.onCompleted: {
rect.color = "red"
}
}Valores estáticos y valores de expresiones de enlace
Como se ha señalado anteriormente, hay dos tipos de valores que pueden asignarse a una propiedad: los valores estáticos y los valores de expresiones de enlace. Estos últimos también se conocen como enlaces de propiedad.
| Tipo | Semántica |
|---|---|
| Valor estático | Un valor constante que no depende de otras propiedades. |
| Expresión de enlace | Expresión de JavaScript que describe la relación de una propiedad con otras propiedades. Las variables de esta expresión se denominan «dependencias» de la propiedad. El motor de QML garantiza la relación entre una propiedad y sus dependencias. Cuando el valor de cualquiera de las dependencias cambia, el motor de QML reevalúa automáticamente la expresión de enlace y asigna el nuevo resultado a la propiedad. |
A continuación se muestra un ejemplo que ilustra ambos tipos de valores asignados a propiedades:
import QtQuick
Rectangle {
// both of these are static value assignments on initialization
width: 400
height: 200
Rectangle {
// both of these are binding expression value assignments on initialization
width: parent.width / 2
height: parent.height
}
}Nota: Para asignar una expresión de enlace de forma imperativa, dicha expresión debe estar contenida en una función que se pase a ` Qt.binding()`, y a continuación el valor devuelto por `Qt.binding()` debe asignarse a la propiedad. Por el contrario, no debe utilizarse `Qt.binding()` al asignar una expresión de enlace durante la inicialización. Consulta «Enlace de propiedades» para obtener más información.
Seguridad de tipos
Las propiedades son seguras en cuanto al tipo. A una propiedad solo se le puede asignar un valor que coincida con el tipo de la propiedad.
Por ejemplo, si una propiedad es de tipo int y se intenta asignarle una cadena, se producirá un error:
property int volume: "four" // generates an error; the property's object will not be loadedDel mismo modo, si a una propiedad se le asigna un valor de tipo incorrecto durante la ejecución, el nuevo valor no se asignará y se generará un error.
Algunos tipos de propiedad no tienen una representación natural de los valores, y para esos tipos de propiedad el motor de QML realiza automáticamente la conversión de cadena a valor tipado. Así, por ejemplo, aunque las propiedades del tipo « color » almacenan colores y no cadenas, se puede asignar la cadena « "red" » a una propiedad de color sin que se produzca ningún error.
Consulta «Tipos de valor de QML» para ver una lista de los tipos de propiedades compatibles de forma predeterminada. Además, cualquier tipo de objeto de QML disponible también puede utilizarse como tipo de propiedad.
Tipos de propiedad especiales
Atributos de las propiedades de lista de objetos
A una propiedad de tipo « list » se le puede asignar una lista de valores de tipo objeto QML. La sintaxis para definir un valor de lista de objetos es una lista separada por comas y entre corchetes:
[ <item 1>, <item 2>, ... ]Por ejemplo, el tipo « Item » tiene una propiedad « states » que se utiliza para contener una lista de objetos de tipo « State ». El código siguiente inicializa el valor de esta propiedad con una lista de tres objetos « State »:
import QtQuick
Item {
states: [
State { name: "loading" },
State { name: "running" },
State { name: "stopped" }
]
}Si la lista contiene un único elemento, se pueden omitir los corchetes:
Una propiedad de tipo « list » puede especificarse en una declaración de objeto con la siguiente sintaxis:
[default] property list<<ObjectType>> propertyNamey, al igual que otras declaraciones de propiedades, la inicialización de una propiedad puede combinarse con la declaración de la propiedad mediante la siguiente sintaxis:
[default] property list<<ObjectType>> propertyName: <value>A continuación se muestra un ejemplo de declaración de una propiedad de tipo lista:
import QtQuick
Rectangle {
// declaration without initialization
property list<Rectangle> siblingRects
// declaration with initialization
property list<Rectangle> childRects: [
Rectangle { color: "red" },
Rectangle { color: "blue"}
]
}Si deseas declarar una propiedad para almacenar una lista de valores que no sean necesariamente valores de tipo objeto QML, debes declarar en su lugar una propiedad « var ».
Propiedades agrupadas
En algunos casos, las propiedades contienen un grupo lógico de atributos de subpropiedades. A estos atributos de subpropiedades se les puede asignar un valor utilizando bien la notación de puntos, bien la notación de grupos.
Por ejemplo, el tipo ` Text ` tiene una propiedad ` font `. A continuación, el primer objeto ` Text ` inicializa sus valores ` font ` mediante la notación de puntos, mientras que el segundo utiliza la notación de grupo:
Text {
//dot notation
font.pixelSize: 12
font.bold: true
}
Text {
//group notation
font { pixelSize: 12; bold: true }
}La sintaxis de propiedades agrupadas está disponible para cualquier propiedad cuyo tipo tenga subpropiedades propias. Se trata de una notación, no de un tipo de propiedad distinto: el hecho de que la propiedad contenga un tipo de valor como ` font ` o un tipo de objeto no supone ninguna diferencia para la sintaxis.
Sin embargo, el tipo de la propiedad sí afecta a lo que debe hacer el motor:
- Si la propiedad contiene un tipo de valor, el motor lee el valor, lo modifica y lo vuelve a escribir. Por lo tanto, la propiedad debe ser escribible.
- Si la propiedad contiene un tipo de objeto, las asignaciones se escriben en el objeto que la propiedad contiene en ese momento. Dicho objeto no debe ser nulo cuando se aplican las asignaciones. La propiedad en sí misma puede ser de solo lectura o modificable. Establecerla como de solo lectura es una forma de evitar que el código QML sustituya el objeto al que pertenecen las subpropiedades, evitando así confusiones sobre a qué objeto se aplican las propiedades agrupadas. Por lo general, es una buena idea.
Los nombres de las subpropiedades se resuelven en función del tipo declarado de la propiedad, no del tipo del objeto que contiene en tiempo de ejecución. Tampoco se pueden utilizar ambas formas para la misma propiedad en la misma definición de objeto: o bien se asigna un objeto a la propiedad, o bien se asigna a sus subpropiedades.
Alias de propiedades
Los alias de propiedad son propiedades que contienen una referencia a otra propiedad. A diferencia de una definición de propiedad ordinaria, que asigna un nuevo espacio de almacenamiento único para la propiedad, un alias de propiedad conecta la propiedad recién declarada (denominada «propiedad alias») como una referencia directa a una propiedad existente (la «propiedad aliasada»).
La declaración de un alias de propiedad se parece a la de una propiedad normal, salvo que requiere la palabra clave « alias » en lugar de un tipo de propiedad, y el lado derecho de la declaración de la propiedad debe ser una referencia de alias válida:
[default] property alias <name>: <alias reference>A diferencia de una propiedad ordinaria, un alias tiene las siguientes restricciones:
- Solo puede hacer referencia a un objeto, o a la propiedad de un objeto, que se encuentre dentro del ámbito del tipo en el que se declara el alias.
- No puede contener expresiones JavaScript arbitrarias.
- No puede hacer referencia a objetos declarados fuera del ámbito de su tipo.
- La referencia al alias no es opcional, a diferencia del valor por defecto opcional de una propiedad ordinaria; la referencia al alias debe proporcionarse cuando se declara el alias por primera vez.
- No puede hacer referencia a propiedades adjuntas.
- No puede hacer referencia a propiedades situadas en una jerarquía con una profundidad de 3 o superior. El siguiente código no funcionará:
property alias color: myItem.myRect.border.color Item { id: myItem property Rectangle myRect }Sin embargo, los alias a propiedades con una profundidad de hasta dos niveles sí funcionarán.
property alias color: rectangle.border.color Rectangle { id: rectangle }
Por ejemplo, a continuación se muestra un tipo « Button » con una propiedad « buttonText » con alias, que está conectada al objeto « text » del elemento secundario « Text »:
// Button.qml
import QtQuick
Rectangle {
property alias buttonText: textItem.text
width: 100; height: 30; color: "yellow"
Text { id: textItem }
}El siguiente código crearía un ` Button ` con una cadena de texto definida para el objeto secundario ` Text `:
Button { buttonText: "Click Me" }En este caso, al modificar buttonText se modifica directamente el valor de textItem.text; no se cambia ningún otro valor que, a su vez, actualice textItem.text. Si buttonText no fuera un alias, cambiar su valor no modificaría en absoluto el texto mostrado, ya que los enlaces de propiedades no son bidireccionales: el valor de buttonText habría cambiado si se modificara textItem.text, pero no al revés.
Alias de propiedades y tipos
Los alias de propiedades no pueden tener especificaciones de tipo explícitas. El tipo de un alias de propiedad es el tipo declarado de la propiedad u objeto al que hace referencia. Por lo tanto, si se crea un alias a un objeto al que se hace referencia mediante id con propiedades adicionales declaradas en línea, no se podrá acceder a dichas propiedades adicionales a través del alias:
// MyItem.qml
Item {
property alias inner: innerItem
Item {
id: innerItem
property int extraProperty
}
}No se puede inicializar ` inner.extraProperty ` desde fuera de este componente, ya que `inner` es únicamente un ` Item`:
// main.qml
MyItem {
inner.extraProperty: 5 // fails
}Sin embargo, si extraes el objeto «inner» a un componente independiente con un archivo .qml específico, puedes instanciar ese componente en su lugar y disponer de todas sus propiedades a través del alias:
// MainItem.qml
Item {
// Now you can access inner.extraProperty, as inner is now an ExtraItem
property alias inner: innerItem
ExtraItem {
id: innerItem
}
}
// ExtraItem.qml
Item {
property int extraProperty
}Propiedades predeterminadas
Una definición de objeto puede tener una única propiedad por defecto. Cuando un objeto se anida directamente dentro de otro sin especificar una propiedad, se le asigna automáticamente la propiedad por defecto del objeto que lo contiene.
Declarar una propiedad con la palabra clave opcional « default » la marca como propiedad por defecto. Por ejemplo, supongamos que hay un archivo Framer.qml con una propiedad por defecto « focusItem »:
// Framer.qml
import QtQuick
Row {
default property Item focusItem
property Item leftItem: Rectangle {
width: 10
height: parent.height
color: "red"
}
property Item rightItem: Rectangle {
width: 10
height: parent.height
color: "blue"
}
children: [leftItem, focusItem, rightItem]
}El valor de « focusItem » se podría asignar en una definición de objeto « Framer », de la siguiente manera:
Framer {
Text { text: "Hello, world!" }
}Esto tiene exactamente el mismo efecto que lo siguiente:
Framer {
focusItem: Text { text: "Hello, world!" }
}Sin embargo, dado que la propiedad « focusItem » se ha marcado como propiedad por defecto, no es necesario asignar explícitamente el objeto « Text » a esta propiedad.
Aunque se puede marcar como propiedad « default » una propiedad de cualquier tipo, por lo general solo resulta útil marcar propiedades de tipo « var », de tipo «object» y sus respectivos tipos de secuencia: Dado que solo se asignan instancias de objeto a la propiedad por defecto, en QML no supone ninguna ventaja tener, por ejemplo, una propiedad de cadena « default ».
Consideremos el siguiente tipo `TextHolder`:
// TextHolder.qml
Item {
property default string mytext
}Por sí solo, esto está bien. Sin embargo, no se puede asignar un literal de cadena a ` mytext ` sin mencionar explícitamente el nombre de la propiedad:
TextHolder {
/* The following would be a syntax error, and will not assign
to the mytext property:
"some text"
The line below is the only way to assign the value:
\1/
mytext: "some text"
}Observarás que se pueden añadir objetos hijos a cualquier tipo basado en ` Item` sin añadirlos explícitamente a la propiedad ` children `. Esto se debe a que la propiedad por defecto de ` Item ` es su propiedad ` data `, y cualquier elemento añadido a esta lista para un ` Item ` se añade automáticamente a su lista de ` children`.
Las propiedades por defecto pueden resultar útiles para reasignar los elementos secundarios de un elemento. Por ejemplo:
Al establecer el alias de la propiedad por defecto en inner.children, cualquier objeto asignado como elemento secundario del elemento exterior se reasigna automáticamente como elemento secundario del elemento interior.
Advertencia: La configuración de los valores de la propiedad de lista por defecto de un elemento puede realizarse de forma implícita o explícita. Dentro de la definición de un mismo elemento, no deben mezclarse estos dos métodos, ya que ello da lugar a un orden indefinido de los elementos de la lista.
Item {
// Use either implicit or explicit assignement to the default list property but not both!
Rectangle { width: 40 } // implicit
data: [ Rectangle { width: 100 } ] // explicit
}Semántica de la sobrescritura
Por defecto, las propiedades pueden quedar enmascaradas: se vuelve a declarar una propiedad en un tipo QML derivado, posiblemente con un nuevo tipo y nuevos atributos. Esto da lugar a dos propiedades con el mismo nombre, de las cuales solo una es accesible en un contexto determinado. Rara vez es esto lo que se desea. A menudo es algo accidental y, en la mayoría de los casos, los efectos resultan bastante confusos. Además, la ocultación es perjudicial para las herramientas.
Para solucionar esto, se introdujeron las palabras clave « virtual », « override » y « final », así como advertencias y errores adicionales.
Para obtener más detalles y un conjunto completo de ejemplos, incluidas las advertencias y los errores, consulta la página «Ocultación de propiedades y semántica de anulación ».
Propiedades obligatorias
Una declaración de objeto puede definir una propiedad como obligatoria utilizando la palabra clave « required ». La sintaxis es
required property <propertyType> <propertyName>Como sugiere el nombre, las propiedades obligatorias deben establecerse al crear una instancia del objeto. El incumplimiento de esta regla provocará que las aplicaciones QML no se inicien si se puede detectar de forma estática. En el caso de componentes QML instanciados dinámicamente (por ejemplo, mediante Qt.createComponent()), el incumplimiento de esta regla da lugar a una advertencia y a un valor de retorno nulo.
Es posible hacer que una propiedad existente sea obligatoria con
required <propertyName>El siguiente ejemplo muestra cómo crear un componente Rectangle personalizado, en el que siempre es necesario especificar la propiedad color.
// ColorRectangle.qml
Rectangle {
required color
}Nota: Nose puede asignar un valor inicial a una propiedad obligatoria desde QML, ya que eso iría directamente en contra del uso previsto de las propiedades obligatorias.
Las propiedades obligatorias desempeñan un papel especial en el código «modelo-vista-delegado»: si el delegado de una vista tiene propiedades obligatorias cuyos nombres coinciden con los nombres de los roles del modelo de la vista, dichas propiedades se inicializarán con los valores correspondientes del modelo. Para obtener más información, visita la página «Modelos y vistas» en Qt Quick.
Consulte QQmlComponent::createWithInitialProperties, QQmlApplicationEngine::setInitialProperties y QQuickView::setInitialProperties para conocer las formas de inicializar propiedades obligatorias desde C++.
Propiedades de solo lectura
Una declaración de objeto puede definir una propiedad de solo lectura utilizando la palabra clave ` readonly `, con la siguiente sintaxis:
readonly property <propertyType> <propertyName> : <value>A las propiedades de solo lectura se les debe asignar un valor estático o una expresión de enlace durante la inicialización. Una vez inicializada una propiedad de solo lectura, ya no es posible modificar su valor estático ni su expresión de enlace.
Por ejemplo, el código del bloque « Component.onCompleted » que aparece a continuación no es válido:
Item {
readonly property int someNumber: 10
Component.onCompleted: someNumber = 20 // TypeError: Cannot assign to read-only property
}Nota: Una propiedad de solo lectura no puede ser también una propiedad por defecto.
Objetos modificadores de propiedades
Las propiedades pueden tener asociados objetos modificadores de valor de propiedad. La sintaxis para declarar una instancia de un tipo de modificador de propiedad asociado a una propiedad concreta es la siguiente:
<PropertyModifierTypeName> on <propertyName> {
// attributes of the object instance
}A esto se le suele denominar sintaxis «on».
Es importante señalar que la sintaxis anterior es, de hecho, una declaración de objeto que instanciará un objeto que actúa sobre una propiedad preexistente.
Ciertos tipos de modificadores de propiedades solo pueden ser aplicables a tipos de propiedades específicos; sin embargo, el lenguaje no impone esta restricción. Por ejemplo, el tipo « NumberAnimation » proporcionado por QtQuick solo animará propiedades de tipo numérico (como int o real). Intentar utilizar un « NumberAnimation » con una propiedad no numérica no dará lugar a un error; sin embargo, la propiedad no numérica no se animará. El comportamiento de un tipo de modificador de propiedad cuando se asocia a un tipo de propiedad concreto viene definido por su implementación.
Atributos de señal
Una señal es una notificación de un objeto que indica que se ha producido algún evento: por ejemplo, que una propiedad ha cambiado, que una animación ha comenzado o se ha detenido, o que se ha descargado una imagen. El tipo ` MouseArea `, por ejemplo, tiene una señal ` clicked ` que se emite cuando el usuario hace clic dentro del área del ratón.
Se puede notificar a un objeto mediante un controlador de señales cada vez que se emite una señal concreta. Un controlador de señales se declara con la sintaxis on<Signal>, donde <Signal> es el nombre de la señal, con la primera letra en mayúscula. El controlador de señales debe declararse dentro de la definición del objeto que emite la señal, y debe contener el bloque de código JavaScript que se ejecutará cuando se invoque el controlador.
Por ejemplo, el controlador de señal onClicked que se muestra a continuación se declara dentro de la definición del objeto MouseArea y se invoca al hacer clic en MouseArea, lo que provoca que se muestre un mensaje en la consola:
import QtQuick
Item {
width: 100; height: 100
MouseArea {
anchors.fill: parent
onClicked: {
console.log("Click!")
}
}
}Definición de atributos de señal
En C++, se puede definir una señal para un tipo registrando un ` Q_SIGNAL ` de una clase que, a su vez, se registra en el sistema de tipos de QML. Alternativamente, se puede definir una señal personalizada para un tipo de objeto en la declaración de dicho objeto dentro de un documento QML con la siguiente sintaxis:
signal <signalName>[([<parameterName>: <parameterType>[, ...]])]Intentar declarar dos señales o métodos con el mismo nombre en el mismo bloque de tipo es un error. Sin embargo, una nueva señal puede reutilizar el nombre de una señal ya existente en el tipo. (Esto debe hacerse con precaución, ya que la señal existente puede quedar oculta y dejar de ser accesible).
A continuación se muestran tres ejemplos de declaraciones de señales:
import QtQuick
Item {
signal clicked
signal hovered()
signal actionPerformed(action: string, actionResult: int)
}También se pueden especificar los parámetros de las señales con la sintaxis de estilo de propiedad:
signal actionCanceled(string action)Para mantener la coherencia con las declaraciones de métodos, es preferible utilizar los dos puntos en las declaraciones de tipos.
Si la señal no tiene parámetros, los paréntesis «()» son opcionales. Si se utilizan parámetros, se deben declarar los tipos de los mismos, como en el caso de los argumentos « string » y « int » de la señal « actionPerformed » anterior. Los tipos de parámetros permitidos son los mismos que los enumerados en la sección «Definición de atributos de propiedad» de esta página.
Para emitir una señal, invócala como un método. Cuando se emita la señal, se invocarán todos los controladores de señal pertinentes, y estos podrán utilizar los nombres de los argumentos de la señal definidos para acceder a los argumentos respectivos.
Señales de cambio de propiedad
Los tipos QML también proporcionan señales de cambio de propiedad integradas que se emiten cada vez que cambia el valor de una propiedad, tal y como se ha descrito anteriormente en la sección sobre atributos de propiedad. Consulta la siguiente sección sobre controladores de señales de cambio de propiedad para obtener más información sobre por qué son útiles estas señales y cómo utilizarlas.
Atributos de los controladores de señales
Los controladores de señales son un tipo especial de atributo de método, en el que el motor de QML invoca la implementación del método cada vez que se emite la señal asociada. Al añadir una señal a la definición de un objeto en QML, se añadirá automáticamente un controlador de señales asociado a dicha definición, que, por defecto, tiene una implementación vacía. Los clientes pueden proporcionar una implementación para poner en práctica la lógica del programa.
Consideremos el siguiente tipo ` SquareButton `, cuya definición se proporciona en el archivo ` SquareButton.qml ` tal y como se muestra a continuación, con las señales ` activated ` y ` deactivated`:
// SquareButton.qml
Rectangle {
id: root
signal activated(xPosition: real, yPosition: real)
signal deactivated
property int side: 100
width: side; height: side
MouseArea {
anchors.fill: parent
onReleased: root.deactivated()
onPressed: mouse => root.activated(mouse.x, mouse.y)
}
}Cualquier objeto de tipo ` SquareButton ` en otro archivo QML del mismo directorio podría recibir estas señales, donde el cliente proporciona las implementaciones de los manejadores de señales:
// myapplication.qml
SquareButton {
onDeactivated: console.log("Deactivated!")
onActivated: (xPosition, yPosition) => {
console.log(`Activated at ${xPosition}, ${yPosition}`)
}
}Los controladores de señales no tienen que declarar los tipos de sus parámetros, ya que la señal ya los especifica. La sintaxis de función flecha mostrada anteriormente no admite anotaciones de tipo.
Consulta el sistema de eventos de señales y controladores para obtener más detalles sobre el uso de las señales.
Manejadores de señales de cambio de propiedad
Los controladores de señales para el cambio de propiedad adoptan la sintaxis on<Property>Changed, donde <Property> es el nombre de la propiedad, con la primera letra en mayúscula. Por ejemplo, aunque la documentación del tipo ` TextInput ` no menciona la señal ` textChanged `, esta señal está implícitamente disponible debido a que ` TextInput ` tiene una propiedad ` text `, por lo que es posible escribir un controlador de señal ` onTextChanged ` que se active cada vez que cambie esta propiedad:
import QtQuick
TextInput {
text: "Change this!"
onTextChanged: console.log(`Text has changed to: ${text}`)
}Atributos de método
Un método de un tipo de objeto es una función a la que se puede llamar para realizar algún procesamiento o desencadenar otros eventos. Un método puede conectarse a una señal de modo que se invoque automáticamente cada vez que se emita la señal. Consulta el sistema de eventos de señales y manejadores para obtener más detalles.
Definición de atributos de método
Se puede definir un método para un tipo en C++ etiquetando una función de una clase que, a continuación, se registra en el sistema de tipos de QML con ` Q_INVOKABLE `, o bien registrándola como un ` Q_SLOT ` de la clase. Como alternativa, se puede añadir un método personalizado a la declaración de un objeto en un documento QML con la siguiente sintaxis:
function <functionName>([<parameterName>[: <parameterType>][, ...]]) [: <returnType>] { <body> }Se pueden añadir métodos a un tipo QML con el fin de definir bloques de código JavaScript independientes y reutilizables. Estos métodos pueden invocarse tanto internamente como desde objetos externos.
A diferencia de las señales, los tipos de los parámetros de los métodos no tienen que declararse, ya que por defecto adoptan el tipo var. No obstante, conviene declararlos para ayudar a qmlcachegen a generar código más eficiente y para mejorar la facilidad de mantenimiento.
Intentar declarar dos métodos o señales con el mismo nombre en el mismo bloque de tipo es un error. No obstante, un nuevo método puede reutilizar el nombre de un método ya existente en el tipo. (Esto debe hacerse con precaución, ya que el método existente podría quedar oculto y volverse inaccesible).
A continuación se muestra un ` Rectangle ` con un método ` calculateHeight() ` que se invoca al asignar el valor ` height `:
import QtQuick
Rectangle {
id: rect
function calculateHeight(): real {
return rect.width / 2;
}
width: 100
height: calculateHeight()
}Si el método tiene parámetros, se puede acceder a ellos por su nombre dentro del propio método. A continuación, al hacer clic en el « MouseArea », se invoca el método « moveTo() », que a su vez puede hacer referencia a los parámetros recibidos « newX » y « newY » para reposicionar el texto:
import QtQuick
Item {
width: 200; height: 200
MouseArea {
anchors.fill: parent
onClicked: mouse => label.moveTo(mouse.x, mouse.y)
}
Text {
id: label
function moveTo(newX: real, newY: real) {
label.x = newX;
label.y = newY;
}
text: "Move me!"
}
}Propiedades adjuntas y controladores de señales adjuntos
Las propiedades adjuntas y los controladores de señales adjuntos son mecanismos que permiten añadir a los objetos propiedades o controladores de señales adicionales a los que, de otro modo, el objeto no tendría acceso. En concreto, permiten a los objetos acceder a propiedades o señales que son específicamente relevantes para cada objeto en particular.
Una implementación de tipo QML puede optar por crear un tipo adjunto en C++ con propiedades y señales concretas. A continuación, se pueden crear instancias de este tipo y adjuntarlas a objetos específicos en tiempo de ejecución, lo que permite a dichos objetos acceder a las propiedades y señales del tipo adjunto. Se accede a ellas anteponiendo el nombre del tipo adjunto a las propiedades y a los respectivos controladores de señales.
Las referencias a las propiedades y los controladores asociados adoptan la siguiente sintaxis:
<AttachingType>.<propertyName>
<AttachingType>.on<SignalName>Por ejemplo, el tipo ` ListView ` tiene una propiedad adjunta ` ListView.isCurrentItem ` que está disponible para cada objeto delegado en un ` ListView`. Cada objeto delegado individual puede utilizarla para determinar si es el elemento seleccionado actualmente en la vista:
import QtQuick
ListView {
width: 240; height: 320
model: 3
delegate: Rectangle {
width: 100; height: 30
color: ListView.isCurrentItem ? "red" : "yellow"
}
}En este caso, el nombre del tipo de adjunto es « ListView » y la propiedad en cuestión es « isCurrentItem », por lo que la propiedad adjunta se denomina « ListView.isCurrentItem ».
Un controlador de señal asociado se denomina de la misma manera. Por ejemplo, el controlador de señal asociado « Component.onCompleted » se utiliza habitualmente para ejecutar código JavaScript cuando ha finalizado el proceso de creación de un componente. En el ejemplo siguiente, una vez que « ListModel » se haya creado por completo, su controlador de señal « Component.onCompleted » se invocará automáticamente para rellenar el modelo:
import QtQuick
ListView {
width: 240; height: 320
model: ListModel {
id: listModel
Component.onCompleted: {
for (let i = 0; i < 10; i++) {
append({ Name: `Item ${i}` })
}
}
}
delegate: Text { text: index }
}Dado que el nombre del tipo de adjunto es « Component » y que dicho tipo cuenta con una señal « completed », el controlador de señal adjunto se denomina « Component.onCompleted ».
Nota sobre el acceso a las propiedades y los controladores de señal adjuntos
Un error habitual es suponer que se puede acceder directamente a las propiedades y a los controladores de señales adjuntos desde los hijos del objeto al que se han adjuntado estos atributos. No es así. La instancia del tipo adjunto solo se adjunta a objetos específicos, no al objeto y a todos sus hijos.
Por ejemplo, a continuación se muestra una versión modificada del ejemplo anterior relacionado con las propiedades adjuntas. En esta ocasión, el delegado es un ` Item ` y el elemento ` Rectangle `, de color, es un elemento secundario de dicho elemento:
import QtQuick
ListView {
width: 240; height: 320
model: 3
delegate: Item {
width: 100; height: 30
Rectangle {
width: 100; height: 30
color: ListView.isCurrentItem ? "red" : "yellow" // WRONG! This won't work.
}
}
}Esto no funciona como se esperaba porque ` ListView.isCurrentItem ` solo está asociada al objeto delegado raíz, y no a sus hijos. Dado que el ` Rectangle ` es un hijo del delegado, en lugar de ser el propio delegado, no puede acceder a la propiedad asociada ` isCurrentItem ` como ` ListView.isCurrentItem`. Por lo tanto, el rectángulo debería acceder a ` isCurrentItem ` a través del delegado raíz:
ListView {
delegate: Item {
id: delegateItem
width: 100; height: 30
Rectangle {
width: 100; height: 30
color: delegateItem.ListView.isCurrentItem ? "red" : "yellow" // correct
}
}
}Ahora delegateItem.ListView.isCurrentItem hace referencia correctamente a la propiedad adjunta isCurrentItem del delegado.
Atributos de enumeración
Las enumeraciones proporcionan un conjunto fijo de opciones con nombre. Se pueden declarar en QML utilizando la palabra clave enum:
// MyText.qml
Text {
enum TextType {
Normal,
Heading
}
}Como se muestra arriba, los tipos de enumeración (p. ej., TextType) y los valores (p. ej., Normal) deben comenzar con una letra mayúscula.
Se hace referencia a los valores mediante <Type>.<EnumerationType>.<Value> o <Type>.<Value>.
// MyText.qml
Text {
enum TextType {
Normal,
Heading
}
property int textType: MyText.TextType.Normal
font.bold: textType === MyText.TextType.Heading
font.pixelSize: textType === MyText.TextType.Heading ? 24 : 12
}Se puede encontrar más información sobre el uso de las enumeraciones en QML en la documentación sobre enumeraciones de QML.
La posibilidad de declarar enumeraciones en Qml se introdujo en Qt 5.10.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.