[Development] QProperty and library coding guide

[Thiago Macieira]

There's a flurry of changes going in right now about using QProperty in 
QObject-derived classes. But before those begin being approved, I'd like to 
see QProperty added to our library coding guide.

Specifically, I want the document to explain:

a) when QProperty should be used and when it shouldn't

b) names to apply to the property getters, setters, signals and property name

c) how to apply QProperty to your properties, when they may be read-only or 
read-writeable, and how to create the change signal (if it carries the new 
value or doesn't)

d) how to write code that is efficient, without double bookkeeping of data; if 
this is not possible in all conditions, suggestions on how to minimise the 
inefficiency. If there's anything class developers need to know about changing 
the values of properties without triggering binding reevaluation unnecessary, 
spell it out.

e) how to write code that is future-compatible with new properties being added 
to the class without breaking binary compatibility

f) how to write code that is future-compatible with class internals changing, 
such as changing the internal representation to be more efficient. Similarly, 
how to use QProperty for properties that are only computed, like these in 
QWidget:
    Q_PROPERTY(int x READ x)
    Q_PROPERTY(int y READ y)
    Q_PROPERTY(QPoint pos READ pos WRITE move DESIGNABLE false STORED false)
    Q_PROPERTY(QPoint pos READ pos WRITE move DESIGNABLE false STORED false)
    Q_PROPERTY(QSize frameSize READ frameSize)
    Q_PROPERTY(QSize size READ size WRITE resize DESIGNABLE false STORED 
false)
    Q_PROPERTY(int width READ width)
    Q_PROPERTY(int height READ height)

In addition, I'd like someone to explain here:

1) how QProperty interacts (or fails to) with dynamic properties, such as QML, 
ActiveQt or QtDBus.

2) if we need to complete transition to QProperty before Qt 6.0; if not, 
explain how leaving some classes un-ported matches the library coding guide.

3) how QProperty is source-compatible with Qt 5 user code.

4) why this overhead is beneficial. For example, QWidget has 59 properties not 
including QObject's, but including the computed ones. Does that mean we're 
adding 59*8 = 472 bytes to 536-byte QWidgetPrivate, an 88% increase? [Note: 
size already includes QString, QList and QByteArray's expansion to 24 bytes].

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel System Software Products