diff options
Diffstat (limited to 'src/declarative/qml')
| -rw-r--r-- | src/declarative/qml/qdeclarativelist.cpp | 113 | ||||
| -rw-r--r-- | src/declarative/qml/qdeclarativeproperty.cpp | 50 |
2 files changed, 150 insertions, 13 deletions
diff --git a/src/declarative/qml/qdeclarativelist.cpp b/src/declarative/qml/qdeclarativelist.cpp index af720d7..9691f32 100644 --- a/src/declarative/qml/qdeclarativelist.cpp +++ b/src/declarative/qml/qdeclarativelist.cpp @@ -85,18 +85,57 @@ void QDeclarativeListReferencePrivate::release() delete this; } +/*! +\class QDeclarativeListReference +\brief The QDeclarativeListReference class allows the manipulation of QDeclarativeListProperty properties. + +QDeclarativeListReference allows programs to read from, and assign values to a QML list property in a +simple and type safe way. A QDeclarativeListReference can be created by passing an object and property +name or through a QDeclarativeProperty instance. These two are equivalant: + +\code +QDeclarativeListReference ref1(object, "children"); + +QDeclarativeProperty ref2(object, "children"); +QDeclarativeListReference ref2 = qvariant_cast<QDeclarativeListReference>(ref2.read()); +\endcode + +Not all QML list properties support all operations. A set of methods, canAppend(), canAt(), canClear() and +canCount() allow programs to query whether an operation is supported on a given property. + +QML list properties are typesafe. Only QObject's that derive from the correct base class can be assigned to +the list. The listElementType() method can be used to query the QMetaObject of the QObject type supported. +Attempting to add objects of the incorrect type to a list property will fail. + +Like with normal lists, when accessing a list element by index, it is the callers responsibility to ensure +that it does not request an out of range element using the count() method before calling at(). +*/ + +/*! +Constructs an invalid instance. +*/ QDeclarativeListReference::QDeclarativeListReference() : d(0) { } -QDeclarativeListReference::QDeclarativeListReference(QObject *o, const char *property, QDeclarativeEngine *engine) +/*! +Constructs a QDeclarativeListReference for \a object's \a property. If \a property is not a list +property, an invalid QDeclarativeListReference is created. If \a object is destroyed after +the reference is constructed, it will automatically become invalid. That is, it is safe to hold +QDeclarativeListReference instances even after \a object is deleted. + +Passing \a engine is required to access some QML created list properties. If in doubt, and an engine +is available, pass it. +*/ +QDeclarativeListReference::QDeclarativeListReference(QObject *object, const char *property, QDeclarativeEngine *engine) : d(0) { - if (!o || !property) return; + if (!object || !property) return; QDeclarativePropertyCache::Data local; - QDeclarativePropertyCache::Data *data = QDeclarativePropertyCache::property(engine, o, QLatin1String(property), local); + QDeclarativePropertyCache::Data *data = + QDeclarativePropertyCache::property(engine, object, QLatin1String(property), local); if (!data || !(data->flags & QDeclarativePropertyCache::Data::IsQList)) return; @@ -106,20 +145,22 @@ QDeclarativeListReference::QDeclarativeListReference(QObject *o, const char *pro if (listType == -1) return; d = new QDeclarativeListReferencePrivate; - d->object = o; + d->object = object; d->elementType = p?p->rawMetaObjectForType(listType):QDeclarativeMetaType::qmlType(listType)->baseMetaObject(); d->propertyType = data->propType; void *args[] = { &d->property, 0 }; - QMetaObject::metacall(o, QMetaObject::ReadProperty, data->coreIndex, args); + QMetaObject::metacall(object, QMetaObject::ReadProperty, data->coreIndex, args); } +/*! \internal */ QDeclarativeListReference::QDeclarativeListReference(const QDeclarativeListReference &o) : d(o.d) { if (d) d->addref(); } +/*! \internal */ QDeclarativeListReference &QDeclarativeListReference::operator=(const QDeclarativeListReference &o) { if (o.d) o.d->addref(); @@ -128,60 +169,108 @@ QDeclarativeListReference &QDeclarativeListReference::operator=(const QDeclarati return *this; } +/*! \internal */ QDeclarativeListReference::~QDeclarativeListReference() { if (d) d->release(); } +/*! +Returns true if the instance refers to a valid list property, otherwise false. +*/ bool QDeclarativeListReference::isValid() const { return d && d->object; } +/*! +Returns the list property's object. Returns 0 if the reference is invalid. +*/ QObject *QDeclarativeListReference::object() const { if (isValid()) return d->object; else return 0; } +/*! +Returns the QMetaObject for the elements stored in the list property. Returns 0 if the reference +is invalid. + +The QMetaObject can be used ahead of time to determine whether a given instance can be added +to a list. +*/ const QMetaObject *QDeclarativeListReference::listElementType() const { if (isValid()) return d->elementType; else return 0; } +/*! +Returns true if the list property can be appended to, otherwise false. Returns false if the +reference is invalid. + +\sa append() +*/ bool QDeclarativeListReference::canAppend() const { return (isValid() && d->property.append); } +/*! +Returns true if the list property can queried by index, otherwise false. Returns false if the +reference is invalid. + +\sa at() +*/ bool QDeclarativeListReference::canAt() const { return (isValid() && d->property.at); } +/*! +Returns true if the list property can be cleared, otherwise false. Returns false if the +reference is invalid. + +\sa clear() +*/ bool QDeclarativeListReference::canClear() const { return (isValid() && d->property.clear); } +/*! +Returns true if the list property can be queried for its element count, otherwise false. +Returns false if the reference is invalid. + +\sa count() +*/ bool QDeclarativeListReference::canCount() const { return (isValid() && d->property.count); } -bool QDeclarativeListReference::append(QObject *o) const +/*! +Appends \a object to the list. Returns true if the operation succeeded, otherwise false. + +\sa canAppend() +*/ +bool QDeclarativeListReference::append(QObject *object) const { if (!canAppend()) return false; - if (o && !QDeclarativePropertyPrivate::canConvert(o->metaObject(), d->elementType)) + if (object && !QDeclarativePropertyPrivate::canConvert(object->metaObject(), d->elementType)) return false; - d->property.append(&d->property, o); + d->property.append(&d->property, object); return true; } +/*! +Returns the list element at \a index, or 0 if the operation failed. + +\sa canAt() +*/ QObject *QDeclarativeListReference::at(int index) const { if (!canAt()) return 0; @@ -189,6 +278,11 @@ QObject *QDeclarativeListReference::at(int index) const return d->property.at(&d->property, index); } +/*! +Clears the list. Returns true if the operation succeeded, otherwise false. + +\sa canClear() +*/ bool QDeclarativeListReference::clear() const { if (!canClear()) return false; @@ -198,6 +292,9 @@ bool QDeclarativeListReference::clear() const return true; } +/*! +Returns the number of objects in the list, or 0 if the operation failed. +*/ int QDeclarativeListReference::count() const { if (!canCount()) return 0; diff --git a/src/declarative/qml/qdeclarativeproperty.cpp b/src/declarative/qml/qdeclarativeproperty.cpp index 9ed760e..e1ec2cd 100644 --- a/src/declarative/qml/qdeclarativeproperty.cpp +++ b/src/declarative/qml/qdeclarativeproperty.cpp @@ -311,10 +311,10 @@ QDeclarativeProperty::QDeclarativeProperty(const QDeclarativeProperty &other) This enum specifies a category of QML property. - \value InvalidCategory The property is invalid. - \value List The property is a QList pointer + \value InvalidCategory The property is invalid, or is a signal property. + \value List The property is a QDeclarativeListProperty list property \value Object The property is a QObject derived type pointer - \value Normal The property is none of the above. + \value Normal The property is a normal value property. */ /*! @@ -752,18 +752,39 @@ QVariant QDeclarativeProperty::read() const return QVariant(); } +/*! +Return the \a name property value of \a object. This method is equivalent to: +\code + QDeclarativeProperty p(object, name); + p.read(); +\endcode +*/ QVariant QDeclarativeProperty::read(QObject *object, const QString &name) { QDeclarativeProperty p(object, name); return p.read(); } +/*! +Return the \a name property value of \a object. This method is equivalent to: +\code + QDeclarativeProperty p(object, name, context); + p.read(); +\endcode +*/ QVariant QDeclarativeProperty::read(QObject *object, const QString &name, QDeclarativeContext *ctxt) { QDeclarativeProperty p(object, name, ctxt); return p.read(); } +/*! +Return the \a name property value of \a object. This method is equivalent to: +\code + QDeclarativeProperty p(object, name, engine); + p.read(); +\endcode +*/ QVariant QDeclarativeProperty::read(QObject *object, const QString &name, QDeclarativeEngine *engine) { QDeclarativeProperty p(object, name, engine); @@ -802,9 +823,7 @@ QVariant QDeclarativePropertyPrivate::readValueProperty() } } -//### //writeEnumProperty MIRRORS the relelvant bit of QMetaProperty::write AND MUST BE KEPT IN SYNC! -//### bool QDeclarativePropertyPrivate::writeEnumProperty(const QMetaProperty &prop, int idx, QObject *object, const QVariant &value, int flags) { if (!object || !prop.isWritable()) @@ -1054,12 +1073,26 @@ bool QDeclarativeProperty::write(const QVariant &value) const return QDeclarativePropertyPrivate::write(*this, value, 0); } +/*! +Writes \a value to the \a name property of \a object. This method is equivalent to: +\code + QDeclarativeProperty p(object, name); + p.write(value); +\endcode +*/ bool QDeclarativeProperty::write(QObject *object, const QString &name, const QVariant &value) { QDeclarativeProperty p(object, name); return p.write(value); } +/*! +Writes \a value to the \a name property of \a object. This method is equivalent to: +\code + QDeclarativeProperty p(object, name, ctxt); + p.write(value); +\endcode +*/ bool QDeclarativeProperty::write(QObject *object, const QString &name, const QVariant &value, QDeclarativeContext *ctxt) { @@ -1067,6 +1100,13 @@ bool QDeclarativeProperty::write(QObject *object, const QString &name, const QVa return p.write(value); } +/*! +Writes \a value to the \a name property of \a object. This method is equivalent to: +\code + QDeclarativeProperty p(object, name, engine); + p.write(value); +\endcode +*/ bool QDeclarativeProperty::write(QObject *object, const QString &name, const QVariant &value, QDeclarativeEngine *engine) { |