El sistema de propiedades
Qt ofrece un sofisticado sistema de propiedades similar a los que proporcionan algunos fabricantes de compiladores. Sin embargo, al ser una biblioteca independiente del compilador y de la plataforma, Qt no depende de características no estándar de los compiladores, como __property o [property]. La solución de Qt funciona con cualquier compilador estándar de C++ en todas las plataformas compatibles con Qt. Se basa en el sistema de metaobjetos, que también permite la comunicación entre objetos mediante señales y ranuras.
Requisitos para declarar propiedades
Para declarar una propiedad, utiliza la macro Q_PROPERTY() en una clase que herede de QObject.
Q_PROPERTY(type name
(READ getFunction [WRITE setFunction] |
MEMBER memberName [(READ getFunction | WRITE setFunction)])
[RESET resetFunction]
[NOTIFY notifySignal]
[REVISION int | REVISION(int[, int])]
[DESIGNABLE bool]
[SCRIPTABLE bool]
[STORED bool]
[USER bool]
[BINDABLE bindableProperty]
[CONSTANT]
[FINAL]
[VIRTUAL]
[OVERRIDE]
[REQUIRED])A continuación se muestran algunos ejemplos típicos de declaraciones de propiedades extraídos de la clase ` QWidget`.
Q_PROPERTY(bool focus READ hasFocus)
Q_PROPERTY(bool enabled READ isEnabled WRITE setEnabled)
Q_PROPERTY(QCursor cursor READ cursor WRITE setCursor RESET unsetCursor)A continuación se muestra un ejemplo que ilustra cómo exportar variables de miembro como propiedades de Qt utilizando la palabra clave ` MEMBER `. Tenga en cuenta que debe especificarse una señal ` NOTIFY ` para permitir los enlaces de propiedades en QML.
Q_PROPERTY(QColor color MEMBER m_color NOTIFY colorChanged)
Q_PROPERTY(qreal spacing MEMBER m_spacing NOTIFY spacingChanged)
Q_PROPERTY(QString text MEMBER m_text NOTIFY textChanged)
//...
signals:
void colorChanged();
void spacingChanged();
void textChanged(const QString &newText);
private:
QColor m_color;
qreal m_spacing;
QString m_text;Una propiedad se comporta como un miembro de datos de clase, pero cuenta con características adicionales a las que se puede acceder a través del sistema de metobjetos.
- Se requiere una función de acceso «
READ» si no se ha especificado ninguna variable «MEMBER». Sirve para leer el valor de la propiedad. Lo ideal es utilizar una función const para este fin, y debe devolver bien el tipo de la propiedad, bien una referencia const a dicho tipo. Por ejemplo, ` QWidget::focus ` es una propiedad de solo lectura con una función `READ`, ` QWidget::hasFocus()`. Si se especifica un `BINDABLE`, se puede escribir `READ default` para que el accesor `READ` se genere a partir de `BINDABLE`. - La función de acceso
WRITEes opcional. Sirve para establecer el valor de la propiedad. Debe devolver void y debe tomar exactamente un argumento, ya sea del tipo de la propiedad o un puntero o referencia a ese tipo. Por ejemplo, QWidget::enabled tiene la funciónWRITEQWidget::setEnabled (). Las propiedades de solo lectura no necesitan funcionesWRITE. Por ejemplo, QWidget::focus no tiene la funciónWRITE. Si se especifican tantoBINDABLEcomoWRITE default, se generará un accesorWRITEa partir deBINDABLE. El accesorWRITEgenerado no emitirá explícitamente ninguna señal declarada conNOTIFY. Se debe registrar la señal como controlador de cambios enBINDABLE, por ejemplo, utilizando Q_OBJECT_BINDABLE_PROPERTY. - Se requiere una asociación de variable
MEMBERsi no se especifica ninguna función de accesoREAD. Esto hace que la variable miembro dada sea legible y escribible sin necesidad de crear funciones de accesoREADyWRITE. Sigue siendo posible utilizar funciones de accesoREADoWRITEademás de la asociación de variableMEMBER(pero no ambas), si necesitas controlar el acceso a la variable. - La función `
RESET` es opcional. Sirve para restablecer la propiedad a su valor por defecto específico del contexto. Por ejemplo, ` QWidget::cursor ` cuenta con las funciones típicas `READ` y `WRITE`, ` QWidget::cursor()` y ` QWidget::setCursor()`, y también tiene una función `RESET`, ` QWidget::unsetCursor()`, ya que la ausencia de una llamada a ` QWidget::setCursor()` puede significar el restablecimiento al cursor específico del contexto. La función `RESET` debe devolver `void` y no tomar parámetros. - La señal «
NOTIFY» es opcional. Si se define, debe especificar una señal existente en esa clase que se emita cada vez que cambie el valor de la propiedad. Las señales «NOTIFY» para las variables «MEMBER» deben tomar cero o un parámetro, que debe ser del mismo tipo que la propiedad. El parámetro tomará el nuevo valor de la propiedad. La señal `NOTIFY` solo debe emitirse cuando la propiedad se haya modificado realmente, para evitar, por ejemplo, que los enlaces se reevalúen innecesariamente en QML. La señal se emite automáticamente cuando la propiedad se modifica a través de la API de Qt (QObject::setProperty, QMetaProperty, etc.), pero no cuando se modifica directamente el `MEMBER`. - Un número de «
REVISION» o una macro «REVISION()» son opcionales. Si se incluyen, definen la propiedad y su señal de notificación para su uso en una revisión concreta de la API (normalmente para su exposición a QML). Si no se incluyen, el valor por defecto es 0. - El atributo «
DESIGNABLE» indica si la propiedad debe ser visible en el editor de propiedades de una herramienta de diseño de interfaces gráficas de usuario (por ejemplo, Qt Widgets Designer). La mayoría de las propiedades son «DESIGNABLE» (valor por defecto: «true»). Los valores válidos son «true» y «false». - El atributo «
SCRIPTABLE» indica si esta propiedad debe ser accesible para un motor de scripts (por defecto, «true»). Los valores válidos son «true» y «false». - El atributo «
STORED» indica si la propiedad debe considerarse independiente o dependiente de otros valores. También indica si el valor de la propiedad debe guardarse al almacenar el estado del objeto. La mayoría de las propiedades son «STORED» (por defecto, «true»), pero, por ejemplo, « QWidget::minimumWidth()» tiene «STORED» establecido en «false», ya que su valor se toma directamente del componente «width» de la propiedad « QWidget::minimumSize()», que es una propiedad « QSize ». - El atributo
USERindica si la propiedad está designada como propiedad visible para el usuario o editable por el usuario para la clase. Normalmente, solo hay una propiedadUSERpor clase (valor por defecto: false). Por ejemplo, QAbstractButton::checked es la propiedad editable por el usuario para los botones (marcables). Ten en cuenta que QItemDelegate obtiene y establece la propiedadUSERde un widget. - El atributo
BINDABLE bindablePropertyindica que la propiedad admite enlaces y que es posible establecer e inspeccionar los enlaces a esta propiedad a través del sistema de metaobjetos (QMetaProperty).bindablePropertydesigna un miembro de clase de tipo QBindable<T>, donde T es el tipo de la propiedad. Este atributo se introdujo en Qt 6.0. - La presencia del atributo
CONSTANTindica que el valor de la propiedad es constante. Para una instancia de objeto dada, el método READ de una propiedad constante debe devolver el mismo valor cada vez que se invoque. Este valor constante puede ser diferente para distintas instancias del objeto. Una propiedad constante no puede tener un método WRITE ni una señal NOTIFY. FINALLos modificadores «VIRTUAL» y «OVERRIDE» reflejan la semántica de sus homólogos en C++ y QML, lo que permite hacer explícita la sobrescritura de propiedades a nivel de metaobjeto.Nota: En la actualidad, moc no impone el uso de estos modificadores. Se reconocen sintácticamente y se utilizan principalmente para la aplicación en QML Runtime y para el diagnóstico de herramientas. Es posible que en futuras versiones se introduzca una validación más estricta en tiempo de compilación y advertencias por sobrescrituras no válidas entre módulos.
Nota: Si deseas cambiar el comportamiento de acceso a una propiedad, utiliza el polimorfismo que ofrece C++.
- La presencia del atributo «
REQUIRED» indica que la propiedad debe ser establecida por un usuario de la clase. Esto no es impuesto por moc y resulta especialmente útil para clases expuestas a QML. En QML, las clases con propiedades «REQUIRED» no pueden instanciarse a menos que se hayan establecido todas las propiedades «REQUIRED».
Las funciones READ, WRITE y RESET pueden heredarse. También pueden ser virtuales. Cuando se heredan en clases en las que se utiliza la herencia múltiple, deben proceder de la primera clase heredada.
El tipo de propiedad puede ser cualquier tipo compatible con ` QVariant`, o bien un tipo definido por el usuario. En este ejemplo, la clase ` QDate ` se considera un tipo definido por el usuario.
Q_PROPERTY(QDate date READ getDate WRITE setDate)Dado que ` QDate ` es un tipo definido por el usuario, debes incluir el archivo de cabecera ` <QDate> ` junto con la declaración de la propiedad.
Por razones históricas, QMap y QList como tipos de propiedad son sinónimos de QVariantMap y QVariantList.
Lectura y escritura de propiedades con el sistema de metaobjetos
Se puede leer y escribir una propiedad utilizando las funciones genéricas ` QObject::property()` y ` QObject::setProperty()`, sin necesidad de conocer nada sobre la clase propietaria, salvo el nombre de la propiedad. En el fragmento de código siguiente, tanto la llamada a ` QAbstractButton::setDown()` como la llamada a ` QObject::setProperty()` establecen la propiedad en «down».
QPushButton *button = new QPushButton;
QObject *object = button;
button->setDown(true);
object->setProperty("down", true);Acceder a una propiedad a través de su accesor WRITE es la mejor de las dos opciones, ya que es más rápido y ofrece mejores diagnósticos en tiempo de compilación, pero establecer la propiedad de esta forma requiere conocer la clase en tiempo de compilación. Acceder a las propiedades por su nombre permite acceder a clases que no se conocen en tiempo de compilación. Se pueden descubrir las propiedades de una clase en tiempo de ejecución consultando sus métodos ` QObject`, ` QMetaObject` y ` QMetaProperties`.
QObject *object = new QObject;
const QMetaObject *metaobject = object->metaObject();
int count = metaobject->propertyCount();
for (int i=0; i<count; ++i) {
QMetaProperty metaproperty = metaobject->property(i);
const char *name = metaproperty.name();
QVariant value = object->property(name);
//...
}En el fragmento de código anterior, se utiliza ` QMetaObject::property()` para obtener ` metadata ` sobre cada propiedad definida en alguna clase desconocida. El nombre de la propiedad se obtiene de los metadatos y se pasa a ` QObject::property()` para obtener el ` value ` de la propiedad en el ` object` actual.
Un ejemplo sencillo
Supongamos que tenemos una clase MyClass, que deriva de QObject y que utiliza la macro Q_OBJECT. Queremos declarar una propiedad en MyClass para llevar un registro de un valor de prioridad. El nombre de la propiedad será priority, y su tipo será un tipo de enumeración denominado Priority, que se define en MyClass.
Declaramos la propiedad con la macro Q_PROPERTY() en la sección privada de la clase. La función READ requerida se denomina priority, e incluimos una función WRITE denominada setPriority. El tipo de enumeración debe registrarse en el sistema de metaoobjetos mediante la macro Q_ENUM(). El registro de un tipo de enumeración permite utilizar los nombres de los elementos de la enumeración en las llamadas a QObject::setProperty(). También debemos proporcionar nuestras propias declaraciones para las funciones « READ » y « WRITE ». La declaración de « MyClass » podría tener entonces el siguiente aspecto:
class MyClass : public QObject
{
Q_OBJECT
Q_PROPERTY(Priority priority READ priority WRITE setPriority NOTIFY priorityChanged)
public:
MyClass(QObject *parent = nullptr);
~MyClass();
enum Priority { High, Low, VeryHigh, VeryLow };
Q_ENUM(Priority)
void setPriority(Priority priority)
{
if (m_priority == priority)
return;
m_priority = priority;
emit priorityChanged(priority);
}
Priority priority() const
{ return m_priority; }
signals:
void priorityChanged(Priority);
private:
Priority m_priority;
};La función READ es const y devuelve el tipo de propiedad. La función WRITE devuelve void y tiene exactamente un parámetro del tipo de propiedad. El Meta-Object Compiler garantiza el cumplimiento de estos requisitos. La comprobación de igualdad en la función WRITE, aunque no es obligatoria, es una buena práctica, ya que no tiene sentido notificar y, potencialmente, forzar una reevaluación en otros lugares si no ha cambiado nada.
Dado un puntero a una instancia de ` MyClass ` o un puntero a un ` QObject ` que sea una instancia de ` MyClass`, disponemos de dos formas de establecer su propiedad de prioridad:
MyClass *myinstance = new MyClass;
QObject *object = myinstance;
myinstance->setPriority(MyClass::VeryHigh);
object->setProperty("priority", "VeryHigh");En el ejemplo, el tipo de enumeración que constituye el tipo de propiedad se declara en MyClass y se registra en el sistema de metaobjetos mediante la macro Q_ENUM(). Esto hace que los valores de la enumeración estén disponibles como cadenas para su uso, tal y como se hace en la llamada a setProperty(). Si el tipo de enumeración se hubiera declarado en otra clase, se requeriría su nombre completo (es decir, OtherClass::Priority), y esa otra clase también tendría que heredar de QObject y registrar allí el tipo de enumeración mediante la macro Q_ENUM().
También está disponible una macro similar, Q_FLAG(). Al igual que Q_ENUM(), registra un tipo de enumeración, pero marca el tipo como un conjunto de indicadores, es decir, valores que se pueden combinar mediante la operación OR. Una clase de E/S podría tener los valores de enumeración Read y Write, y entonces QObject::setProperty() podría aceptar Read | Write. Se debería utilizar Q_FLAG() para registrar este tipo de enumeración.
Propiedades dinámicas
QObject::setProperty() también se puede utilizar para añadir nuevas propiedades a una instancia de una clase en tiempo de ejecución. Cuando se invoca con un nombre y un valor, si existe una propiedad con el nombre dado en QObject y si el valor dado es compatible con el tipo de la propiedad, el valor se almacena en la propiedad y se devuelve «true». Si el valor no es compatible con el tipo de la propiedad, la propiedad no se modifica y se devuelve «false». Sin embargo, si la propiedad con el nombre especificado no existe en QObject (es decir, si no se declaró con Q_PROPERTY()), se añade automáticamente una nueva propiedad con el nombre y el valor especificados a QObject, pero se devuelve «false» de todos modos. Esto significa que no se puede utilizar el valor «false» devuelto para determinar si una propiedad concreta se ha establecido realmente, a menos que se sepa de antemano que la propiedad ya existe en QObject.
Ten en cuenta que las propiedades dinámicas se añaden por instancia, es decir, se añaden a QObject, no a QMetaObject. Una propiedad puede eliminarse de una instancia pasando el nombre de la propiedad y un valor no válido QVariant a QObject::setProperty(). El constructor por defecto de QVariant crea un QVariant no válido.
Las propiedades dinámicas se pueden consultar con QObject::property(), al igual que las propiedades declaradas en tiempo de compilación con Q_PROPERTY().
Propiedades y tipos personalizados
Los tipos personalizados utilizados por las propiedades deben registrarse mediante la macro Q_DECLARE_METATYPE(), de modo que sus valores puedan almacenarse en objetos QVariant. Esto los hace adecuados para su uso tanto con propiedades estáticas declaradas mediante la macro Q_PROPERTY() en las definiciones de clase como con propiedades dinámicas creadas en tiempo de ejecución.
Añadir información adicional a una clase
Relacionada con el sistema de propiedades hay una macro adicional, Q_CLASSINFO(), que puede utilizarse para adjuntar paresnombre-valor adicionales al metaobjeto de una clase. Esto se utiliza, por ejemplo, para marcar una propiedad como la predeterminada en el contexto de QML Object Types:
Q_CLASSINFO("DefaultProperty", "content")Al igual que otros metadatos, se puede acceder a la información de la clase en tiempo de ejecución a través del metaobjeto; véase QMetaObject::classInfo() para más detalles.
Uso de propiedades vinculables
Se pueden utilizar tres tipos diferentes para implementar propiedades vinculables:
El primero es una clase general para propiedades vinculables. Los dos últimos solo pueden utilizarse dentro de un ` QObject`.
Para obtener más información, incluidos ejemplos, consulta las clases mencionadas anteriormente y los consejos generales sobre la implementación y el uso de propiedades enlazables.
Véase también «Sistema de metaojetos», «Señales y ranuras», « Q_DECLARE_METATYPE()», « QMetaType », « QVariant », «Propiedades vinculables de Qt» y «Definición de tipos QML desde C++».
© 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.