QQmlPropertyMap Class Reference

The QQmlPropertyMap class allows you to set key-value pairs that can be used in QML bindings. More...

#include <qqmlpropertymap.h>

Inheritance diagram for QQmlPropertyMap:

Collaboration diagram for QQmlPropertyMap:

Signals
void	valueChanged (const QString &key, const QVariant &value)
	This signal is emitted whenever one of the values in the map is changed.
Signals inherited from QObject
void	destroyed (QObject *=nullptr)
	This signal is emitted immediately before the object obj is destroyed, after any instances of QPointer have been notified, and cannot be blocked.
void	objectNameChanged (const QString &objectName, QPrivateSignal)
	This signal is emitted after the object's name has been changed.

Public Member Functions
	QQmlPropertyMap (QObject *parent=nullptr)
	Constructs a bindable map with parent object parent.
	~QQmlPropertyMap () override
	Destroys the bindable map.
QVariant	value (const QString &key) const
	Returns the value associated with key.
void	insert (const QString &key, const QVariant &value)
	Sets the value associated with key to value.
void	insert (const QVariantHash &values)
void	clear (const QString &key)
	Clears the value (if any) associated with key.
void	freeze ()
Q_INVOKABLE QStringList	keys () const
	Returns the list of keys.
int	count () const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Same as size().
int	size () const
	Returns the number of keys in the map.
bool	isEmpty () const
	Returns true if the map contains no keys; otherwise returns false.
bool	contains (const QString &key) const
	Returns true if the map contains key.
QVariant &	operator[] (const QString &key)
	Returns the value associated with the key key as a modifiable reference.
QVariant	operator[] (const QString &key) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Same as value().
Public Member Functions inherited from QObject
Q_INVOKABLE	QObject (QObject *parent=nullptr)
	Constructs an object with parent object parent.
virtual	~QObject ()
	Destroys the object, deleting all its child objects.
virtual bool	event (QEvent *event)
	This virtual function receives events to an object and should return true if the event e was recognized and processed.
virtual bool	eventFilter (QObject *watched, QEvent *event)
	Filters events if this object has been installed as an event filter for the watched object.
QString	objectName () const
Q_WEAK_OVERLOAD void	setObjectName (const QString &name)
	Sets the object's name to name.
void	setObjectName (QAnyStringView name)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
QBindable< QString >	bindableObjectName ()
bool	isWidgetType () const
	Returns true if the object is a widget; otherwise returns false.
bool	isWindowType () const
	Returns true if the object is a window; otherwise returns false.
bool	isQuickItemType () const
	Returns true if the object is a QQuickItem; otherwise returns false.
bool	signalsBlocked () const noexcept
	Returns true if signals are blocked; otherwise returns false.
bool	blockSignals (bool b) noexcept
	If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it).
QThread *	thread () const
	Returns the thread in which the object lives.
bool	moveToThread (QThread *thread QT6_DECL_NEW_OVERLOAD_TAIL)
	Changes the thread affinity for this object and its children and returns true on success.
int	startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
	This is an overloaded function that will start a timer of type timerType and a timeout of interval milliseconds.
int	startTimer (std::chrono::nanoseconds time, Qt::TimerType timerType=Qt::CoarseTimer)
void	killTimer (int id)
	Kills the timer with timer identifier, id.
void	killTimer (Qt::TimerId id)
template<typename T >
T	findChild (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	Returns the child of this object that can be cast into type T and that is called name, or \nullptr if there is no such object.
template<typename T >
QList< T >	findChildren (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects.
template<typename T >
T	findChild (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
template<typename T >
QList< T >	findChildren (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
const QObjectList &	children () const
	Returns a list of child objects.
void	setParent (QObject *parent)
	Makes the object a child of parent.
void	installEventFilter (QObject *filterObj)
	Installs an event filter filterObj on this object.
void	removeEventFilter (QObject *obj)
	Removes an event filter object obj from this object.
QMetaObject::Connection	connect (const QObject *sender, const char *signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const
bool	disconnect (const char *signal=nullptr, const QObject *receiver=nullptr, const char *member=nullptr) const
bool	disconnect (const QObject *receiver, const char *member=nullptr) const
void	dumpObjectTree () const
	Dumps a tree of children to the debug output.
void	dumpObjectInfo () const
	Dumps information about signal connections, etc.
bool	setProperty (const char *name, const QVariant &value)
	Sets the value of the object's name property to value.
bool	setProperty (const char *name, QVariant &&value)
QVariant	property (const char *name) const
	Returns the value of the object's name property.
QList< QByteArray >	dynamicPropertyNames () const
QBindingStorage *	bindingStorage ()
const QBindingStorage *	bindingStorage () const
QObject *	parent () const
	Returns a pointer to the parent object.
bool	inherits (const char *classname) const
	Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns false.

Protected Member Functions
virtual QVariant	updateValue (const QString &key, const QVariant &input)
	Returns the new value to be stored for the key key.
template<class DerivedType >
	QQmlPropertyMap (DerivedType *derived, QObject *parentObj)
	Constructs a bindable map with parent object parent.
Protected Member Functions inherited from QObject
QObject *	sender () const
	Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns \nullptr.
int	senderSignalIndex () const
int	receivers (const char *signal) const
	Returns the number of receivers connected to the signal.
bool	isSignalConnected (const QMetaMethod &signal) const
virtual void	timerEvent (QTimerEvent *event)
	This event handler can be reimplemented in a subclass to receive timer events for the object.
virtual void	childEvent (QChildEvent *event)
	This event handler can be reimplemented in a subclass to receive child events.
virtual void	customEvent (QEvent *event)
	This event handler can be reimplemented in a subclass to receive custom events.
virtual void	connectNotify (const QMetaMethod &signal)
virtual void	disconnectNotify (const QMetaMethod &signal)
	QObject (QObjectPrivate &dd, QObject *parent=nullptr)

Additional Inherited Members
Public Slots inherited from QObject
void	deleteLater ()
	\threadsafe
Static Public Member Functions inherited from QObject
static QMetaObject::Connection	connect (const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
	\threadsafe
static QMetaObject::Connection	connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)
template<typename Func1 , typename Func2 >
static QMetaObject::Connection	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const typename QtPrivate::ContextTypeForFunctor< Func2 >::ContextType *context, Func2 &&slot, Qt::ConnectionType type=Qt::AutoConnection)
template<typename Func1 , typename Func2 >
static QMetaObject::Connection	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, Func2 &&slot)
static bool	disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *member)
	\threadsafe
static bool	disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &member)
static bool	disconnect (const QMetaObject::Connection &)
	Disconnect a connection.
template<typename Func1 , typename Func2 >
static bool	disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const typename QtPrivate::FunctionPointer< Func2 >::Object *receiver, Func2 slot)
template<typename Func1 >
static bool	disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const QObject *receiver, void **zero)
Protected Attributes inherited from QObject
QScopedPointer< QObjectData >	d_ptr
Properties inherited from QObject
QString	objectName
	the name of this object
Related Symbols inherited from QObject
template< class T > T	qobject_cast (const QObject *object)
	Returns the given object cast to type T if the object is of type T (or of a subclass); otherwise returns \nullptr.
template< typename T > T	qFindChildqFindChildren (const QObject *obj, const QString &name)()
template< typename T > QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QString &name)()
	QObjectList
	\macro Q_CLASSINFO(Name, Value)

Detailed Description

The QQmlPropertyMap class allows you to set key-value pairs that can be used in QML bindings.

\inmodule QtQml

QQmlPropertyMap provides a convenient way to expose domain data to the UI layer. The following example shows how you might declare data in C++ and then access it in QML.

In the C++ file:

// create our data
QQmlPropertyMap ownerData;
ownerData.insert("name", QVariant(QString("John Smith")));
ownerData.insert("phone", QVariant(QString("555-5555")));
 
// expose it to the UI layer
QQuickView view;
QQmlContext *ctxt = view.rootContext();
ctxt->setContextProperty("owner", &ownerData);
 
view.setSource(QUrl::fromLocalFile("main.qml"));
view.show();

Then, in main.qml:

Text { text: owner.name + " " + owner.phone }

The binding is dynamic - whenever a key's value is updated, anything bound to that key will be updated as well.

To detect value changes made in the UI layer you can connect to the valueChanged() signal. However, note that valueChanged() is NOT emitted when changes are made by calling insert() or clear() - it is only emitted when a value is updated from QML.

Note

It is not possible to remove keys from the map; once a key has been added, you can only modify or clear its associated value.

When deriving a class from QQmlPropertyMap, use the \l {QQmlPropertyMap::QQmlPropertyMap(DerivedType *derived, QObject *parent)} {protected two-argument constructor} which ensures that the class is correctly registered with the Qt \l {Meta-Object System}.

The QMetaObject of a QQmlPropertyMap is dynamically generated and modified. Operations on that meta object are not thread safe, so applications need to take care to explicitly synchronize access to the meta object.

Definition at line 18 of file qqmlpropertymap.h.

Constructor & Destructor Documentation

QQmlPropertyMap() [1/2]

QQmlPropertyMap::QQmlPropertyMap ( QObject * parent = nullptr )

explicit

Constructs a bindable map with parent object parent.

Definition at line 148 of file qqmlpropertymap.cpp.

~QQmlPropertyMap()

QQmlPropertyMap::~QQmlPropertyMap ( )

override

Destroys the bindable map.

Definition at line 156 of file qqmlpropertymap.cpp.

QQmlPropertyMap() [2/2]

template<class DerivedType >

template< class DerivedType > QQmlPropertyMap::QQmlPropertyMap ( DerivedType * derived, QObject * parent )

inlineprotected

Constructs a bindable map with parent object parent.

Use this constructor in classes derived from QQmlPropertyMap.

The type of derived is used to register the property map with the \l {Meta-Object System}, which is necessary to ensure that properties of the derived class are accessible. This type must be derived from QQmlPropertyMap.

Definition at line 48 of file qqmlpropertymap.h.

References derived, and Q_UNUSED.

Member Function Documentation

clear()

void QQmlPropertyMap::clear

(

const QString &

key

)

Clears the value (if any) associated with key.

Definition at line 163 of file qqmlpropertymap.cpp.

References d.

contains()

bool QQmlPropertyMap::contains

(

const QString &

key

)

const

Returns true if the map contains key.

See also

size()

Definition at line 297 of file qqmlpropertymap.cpp.

References d.

count()

int QQmlPropertyMap::count

(

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Same as size().

Definition at line 263 of file qqmlpropertymap.cpp.

References d.

freeze()

void QQmlPropertyMap::freeze

(

)

Since

6.1

Disallows any further properties to be added to this property map. Existing properties can be modified or cleared.

In turn, an internal cache is turned on for the existing properties, which may result in faster access from QML.

Definition at line 179 of file qqmlpropertymap.cpp.

References d.

insert() [1/2]

void QQmlPropertyMap::insert	(	const QString &	key,
		const QVariant &	value )

Sets the value associated with key to value.

If the key doesn't exist, it is automatically created.

Definition at line 203 of file qqmlpropertymap.cpp.

References d, and qWarning.

Referenced by operator[]().

Here is the caller graph for this function:

insert() [2/2]

void QQmlPropertyMap::insert

(

const QVariantHash &

values

)

Since

6.1

Inserts the values into the QQmlPropertyMap.

Keys that don't exist are automatically created.

This method is substantially faster than calling {insert(key, value)} many times in a row.

Definition at line 226 of file qqmlpropertymap.cpp.

References QSet< T >::begin(), d, it, and qWarning.

Here is the call graph for this function:

isEmpty()

bool QQmlPropertyMap::isEmpty

(

)

const

Returns true if the map contains no keys; otherwise returns false.

See also

size()

Definition at line 286 of file qqmlpropertymap.cpp.

References d.

keys()

QStringList QQmlPropertyMap::keys

(

)

const

Returns the list of keys.

Keys that have been cleared will still appear in this list, even though their associated values are invalid QVariants.

Definition at line 252 of file qqmlpropertymap.cpp.

References d.

Referenced by QDeclarativePlace::place().

Here is the caller graph for this function:

operator[]() [1/2]

QVariant & QQmlPropertyMap::operator[]

(

const QString &

key

)

Returns the value associated with the key key as a modifiable reference.

If the map contains no item with key key, the function inserts an invalid QVariant into the map with key key, and returns a reference to it.

See also

insert(), value()

Definition at line 313 of file qqmlpropertymap.cpp.

References d, and insert().

Here is the call graph for this function:

operator[]() [2/2]

QVariant QQmlPropertyMap::operator[]

(

const QString &

key

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Same as value().

Definition at line 329 of file qqmlpropertymap.cpp.

size()

int QQmlPropertyMap::size

(

)

const

Returns the number of keys in the map.

See also

isEmpty(), count()

Definition at line 274 of file qqmlpropertymap.cpp.

References d.

updateValue()

QVariant QQmlPropertyMap::updateValue ( const QString & key, const QVariant & input )

protectedvirtual

Returns the new value to be stored for the key key.

This function is provided to intercept updates to a property from QML, where the value provided from QML is input.

Override this function to manipulate the property value as it is updated. Note that this function is only invoked when the value is updated from QML.

Reimplemented in QDeclarativeContactDetails.

Definition at line 341 of file qqmlpropertymap.cpp.

References Q_UNUSED.

value()

QVariant QQmlPropertyMap::value

(

const QString &

key

)

const

Returns the value associated with key.

If no value has been set for this key (or if the value has been cleared), an invalid QVariant is returned.

Definition at line 192 of file qqmlpropertymap.cpp.

References d.

Referenced by QDeclarativePlace::place().

Here is the caller graph for this function:

valueChanged

void QQmlPropertyMap::valueChanged ( const QString & key, const QVariant & value )

signal

This signal is emitted whenever one of the values in the map is changed.

key is the key corresponding to the value that was changed.

Note

valueChanged() is NOT emitted when changes are made by calling insert() or clear() - it is only emitted when a value is updated from QML.

Referenced by QDeclarativePlace::QDeclarativePlace(), QDeclarativePlace::QDeclarativePlace(), and QQmlBindPrivate::createDelayedValues().

Here is the caller graph for this function:

---

The documentation for this class was generated from the following files:

• qtdeclarative/src/qml/util/qqmlpropertymap.h (0dc4fd240a2897c5c443a0ef6d84c416843e4938)
• qtdeclarative/src/qml/util/qqmlpropertymap.cpp (958cd3ee1094a068b6d0ff27c73a4b3caff088ad)